Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Update docs for OpenAPI. #6668
Hey @carltongibson, is this largely ready to go, or is there more to do? What else would be left?
I'm mostly indifferent. We either start here, or we update it all in one go in the release PR.
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 -
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)?
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.)