Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for OpenAPI. #6668

Merged
merged 6 commits into from Jul 8, 2019

Conversation

@carltongibson
Copy link
Collaborator

commented May 13, 2019

Follow up to #6532.

  • Adds documentation for OpenAPI
  • Moves CoreAPI docs to Legacy folder (until v3.12)
  • Add release announcement for v3.10

Closes #6381

mkdocs.yml Outdated Show resolved Hide resolved
REST framework provides built-in support for generating OpenAPI schemas, which
can be used with tools that allow you to build API documentation.

There are also a number of great third-party documentation packages available.

This comment has been minimized.

Copy link
@carltongibson

carltongibson May 29, 2019

Author Collaborator

Hey @tomchristie. Can you review the Third party section on this page at 1d3a3ee?

I ≈think we could just drop it...

  • drf-yasg is already mentioned on the Schema page, and it's not about Docs.
  • Not sure if DRF AutoDocs and/or Django REST Swagger are still active.
  • Is Apiary still worth calling out (from all the commercial solutions available now)?

Seems like a reasonable chance to review. Thanks!

This comment has been minimized.

Copy link
@carltongibson

carltongibson Jun 9, 2019

Author Collaborator

Ref @rpkilby's #6733

@carltongibson carltongibson force-pushed the openapi-docs-updates branch from e57ec35 to ae61385 Jun 9, 2019

@carltongibson

This comment has been minimized.

Copy link
Collaborator Author

commented Jun 9, 2019

Hey @tomchristie. This is about right for me. Sorry for the delay.

I split it into two commits:

  • Update the docs
  • Begin the release announcement.

My thought was that we perhaps pull the second into the release PR, rather than here.

@carltongibson carltongibson force-pushed the openapi-docs-updates branch from ae61385 to 3fb872b Jun 9, 2019

@pajusmar
Copy link
Contributor

left a comment

Fixed some typos.

docs/topics/documenting-your-api.md Outdated Show resolved Hide resolved
docs/topics/documenting-your-api.md Outdated Show resolved Hide resolved
docs/topics/documenting-your-api.md Outdated Show resolved Hide resolved
docs/topics/documenting-your-api.md Outdated Show resolved Hide resolved

carltongibson and others added some commits Jun 10, 2019

Update docs/topics/documenting-your-api.md
Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com>
Update docs/topics/documenting-your-api.md
Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com>
Update docs/topics/documenting-your-api.md
Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com>
Update docs/topics/documenting-your-api.md
Co-Authored-By: Martin Pajuste <pajusmar@users.noreply.github.com>
@carltongibson

This comment has been minimized.

Copy link
Collaborator Author

commented Jun 10, 2019

Thanks @pajusmar!

@rpkilby

This comment has been minimized.

Copy link
Member

commented Jul 3, 2019

Hey @carltongibson, is this largely ready to go, or is there more to do? What else would be left?

I split it into two commits:

  • Update the docs
  • Begin the release announcement.

My thought was that we perhaps pull the second into the release PR, rather than here.

I'm mostly indifferent. We either start here, or we update it all in one go in the release PR.

@carltongibson

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 3, 2019

Hey Ryan. For me it's ≈ready. (Totally happy if people want adjust but ...)

@tomchristie

This comment has been minimized.

Copy link
Member

commented Jul 3, 2019

I'm good with this too. Planning to roll the release first thing next week.
I guess we could already merge this as-is, and then work a release PR from there?

@tomchristie

This comment has been minimized.

Copy link
Member

commented Jul 3, 2019

One thing we've not talked about in the release which I guess will come up is "what about the coreapi client" esp. since we're actually dropping a part of the tutorial here. Not exactly sure what the right answer is there - apistar can potentially fill that gap, but it's not there yet, and given all the various spinning plates I don't know how much of a priority it's going to be.

It could be that we need apistar to be an adequate schema-driven API client in time for the 3.11 release (potentially also with nice API docs building that we can demo how to integrate in 3.11)?

Any thoughts?

@carltongibson

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 3, 2019

Any thoughts?

Well, yes. 🙂

I decided to drop the tutorial because, ultimately, I think including the interactive docs and client usage is out of scope for DRF. I think we over-reached there.

There are a whole load of tools out there that people can use, but beyond generating the schema, and OK, showing a basic integration so you can get some nice docs up, I think we need to stay out of that domain. (Maybe linking to a couple of the obvious options for tooling...)

I'm expecting that folks will pick up an OpenAPI eating client and report issues with the generated schema that we can fix in 3.10.1, .2, .3, ... and so on.

What I don't see is that DRF needs to provide such a client itself. As and when APIStar gets there, great, but even then I wouldn't replace the Tutorial step. (I'd link to the APIStar docs from the Documenting your API topic page.)

@carltongibson

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 3, 2019

Also, one TODO: once this is merged, links to the rendered MD pages on GitHub for the legacy docs can be inserted/corrected. (I thought to link just to the index page from the release notes, and maybe for a version from Schemas too.)

@tomchristie

This comment has been minimized.

Copy link
Member

commented Jul 3, 2019

Okay I think that's really well balanced, yup. 👍

I might flesh out a bit of release notes with that in mind.

@tomchristie

This comment has been minimized.

Copy link
Member

commented Jul 8, 2019

Alrighty, going to merge this in, and make any further changes during the 3.10 PR.
Thanks so much for your work here, @carltongibson! 💙

@tomchristie tomchristie merged commit 7915485 into master Jul 8, 2019

2 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

@tomchristie tomchristie deleted the openapi-docs-updates branch Jul 8, 2019

@tomchristie tomchristie referenced this pull request Jul 8, 2019
4 of 18 tasks complete
@tomchristie tomchristie referenced this pull request Jul 15, 2019
18 of 18 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.