REST framework 3.4 - Schema generation.

[tomchristie]

Opening this up in order to start the conversation...

So, I'm working towards a 3.4 release. The headline features here are schema generation and client libraries.

Pull request: encode/django-rest-framework#4179
Upcoming new tutorial section: https://github.com/tomchristie/django-rest-framework/blob/schema-support/docs/tutorial/7-schemas-and-client-libraries.md

I think the client library support in particular is a big deal, and using Core API as the internal representation format is a necessary part of that.

Essentially we'll have a single built-in method for handling introspection, that returns a Core API Document object representing the schema. Various different renderers can then be built in order to translate the Core API Document into either a rendered set of documentation, or into a rendered schema, such as a swagger document.

• django-rest-swagger could move away from providing it's own introspection, and rely on what's in core, instead just handling the rendering of a Core API document, and URLs/views for serving the documentation templates that swagger provides.
• There will very likely be a coreapi-openapi package, that provides a Document<->Swagger/OpenAPI codec. (right now the coreapi package has swagger decoding built-in, but I'd really like to pull out the individual schema formats, with the exception of corejson, which serves as a canonical representation format), so django-rest-swagger could additionally rely on that for the rendering, providing just the wrapping for a REST framework renderer that uses the codec, plus the URLs/views for serving the documentation templates that swagger provides.

There's also some provisos that this introduces...

Core API can be mapped pretty well onto a swagger document, but there will be a few places where we might need to smooth things over a bit. Eg. we don't represent the expected status codes of a response in a link, because it's not actually behaviorally necessary in order to drive a dynamic client. We can consider how to best handle these aspects as we come to them.

Anyways, I'll leave it at that for now. Any thoughts/feedback welcome. The django-rest-swagger could just stay exactly as it is of course and all would be fine, but this is an interesting oppurtunity for us to make it much easier for developers to support a wide range of schema formats and documentation styles, and it might be worth considering if we could transition django-rest-swagger to leveraging the built-in schema support.

[tomchristie]

Aside: don't treat the current implementation of the schema generation as anything more than a proof of concept - I needed something I could use against which to write the tutorial section. The final implementation is almost certainly going to be much more similar to how django-rest-swagger works.

[marcgibbons]

@tomchristie Thanks for this. As it turns out, I have started a rewrite/refactor of the project; it would be great to leverage a common API for inspection or even roll up this functionality / project completely into the DRF core. The high-level objectives are listed in #443.

I really like the direction of generating library agnostic specs and see lots of potential in both docs, and in the OPTIONS metaclasses.

Would be great to connect and coordinate the effort!

[tomchristie]

and in the OPTIONS metaclasses.

Agreed. This will certainly make its way into OPTIONS metadata classes too, tho I'm not sure yet if that'll be as part of 3.4 or 3.5. (The sooner we can get the core bits of this out the better)

[tomchristie]

Oops fat fingers

[tomchristie]

Schema documentation now roughly complete: https://github.com/tomchristie/django-rest-framework/blob/schema-support/docs/api-guide/schemas.md

Ideally would be good to see Swagger package alongside the 3.4 release, as it'd be a good test of if the schema implementation is sufficient for your package's requirements. I may be able to put some work in there, tho I'll start of with tackling remaining stuff on the schema ticket.

[marcgibbons]

@tomchristie Closing this out as the release is complete. Congratulations on 3.4!

I am doing a triage of open tickets in this project to come up with a feature list for the schema generator.