On 7/8/19 7:41 pm, Stephen Finucane wrote:
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.
I got there in the end!
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.
Yes, I realised it was being used for validation after the number of
fixes I had to make to get the tests passing :)
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 :(
That's unfortunate.
--
Andrew Donnellan OzLabs, ADL Canberra
a...@linux.ibm.com IBM Australia Limited
_______________________________________________
Patchwork mailing list
Patchwork@lists.ozlabs.org
https://lists.ozlabs.org/listinfo/patchwork
