OpenAPI schema

[Stephen Finucane]

On Wed, 2019-08-07 at 17:10 +1000, Andrew Donnellan wrote:
> Currently working on some patches that add some extra fields to the API.
> 
> Updating the OpenAPI schema, especially with the jinja2 templating that 
> we use for versioning, is difficult, especially for those of us with no 
> background in the OpenAPI format. patchwork.j2 is >2300 lines long, 
> which is more than 2x the LOC in the api directory as measured by sloccount.

I can help with this. Just let me know what you'd like to add. If you
wanted to do it yourself, I'd personally modify the generated v1.2 API
using one of the many online schema editors (like 
https://editor.swagger.io/) and then feed the changes back into the
template when you're done.

> Does anyone even use the OpenAPI schema for anything?

We use it for two things: API documentation and validation (i.e.
tests). The API documentation was my initial goal but the validation
part of things helped me uncover quite a few bugs in the API and (I
imagine) will help prevent more in the future. It was also a chance to
play around with OpenAPI, which is nice. I'd like to keep it around,
even if it means I have to make any changes necessary.

> I note that DRF apparently has some native support for OpenAPI schema 
> generation (https://www.django-rest-framework.org/api-guide/schemas/) - 
> can we use that? Perhaps with a custom schema generator to handle API 
> versioning.

I checked this out (and submitted a few patches to correct some of the
many bugs in earlier versions of it). Unfortunately, the schema it
generates is far too lossy to be useful, and it does particularly
poorly with things that are autogenerated or more freeform
fields/filters. I also looked through a couple of Django extensions but
they suffered the same issue. As nice as it would have been to auto-
generate this stuff, it just wasn't an issue, sadly :(

Stephen