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 _______________________________________________ Patchwork mailing list Patchwork@lists.ozlabs.org https://lists.ozlabs.org/listinfo/patchwork
