OpenAPI schema

[Andrew Donnellan]

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
ajd at linux.ibm.com             IBM Australia Limited