OpenAPI 2.0 schema generation – drf-yasg-json-api

[glowka]

Hello @sliverc!

After using django-rest-framework-json-api (thanks for developing it!) in couple of projects I really lacked quick way to expose developed API with swagger or other tool of that kind. From available back then (1,5yr ago) packages, that supplied similar functionality for pure django-rest-framework, one particular package worked much better than built-in schema generation functionality of django-rest-framework – it was drf-yasg which automatically inspects all serializers and views to successfully generate complete request/response schema. I decided to follow drf-yasg robust inspection-based architecture by implementing inspectors that would generate valid json api schema for views that use JSONAPIRenderer and JSONAPIParser. I applied these new inspectors in my projects and covered all schema generation cases I needed, then I published it as drf-yasg-json-api (https://github.com/glowka/drf-yasg-json-api).

The package focuses on generating schema for standard views and viewsets with all serializer-derived fields as well as filters, pagination and include function. There is no support for some additional json api views like RelationshipView. Detailed features are described in this section of README: https://github.com/glowka/drf-yasg-json-api#features

It's been one year since I published this package, I of course keep using it, some people stared using it as well. The code seems to be quite reliable. So, at this stage, I decided to ask you @sliverc to take a look at drf-yasg-json-api and consider if it makes sense for you to mention somewhere in docs about drf-yasg-json-api as package compatible with and functionally complementary to django-rest-framework-json-api. Could it be, in your opinion, interesting for django-rest-framework-json-api users and worth mentioning? How do you think?

Thanks in advance for your consideration!

Best,
Tom

[sliverc]

It is great to see that based on DJA other libraries are developed.

I would suggest within the documentation a 3rd package page in the spirit of DRF should be created where a link to drf-yasg-json-api can be added.

I am in full favor to support devs to create 3rd packages to integrate new DJA features instead of adding them to core. This will also help us improve the API of DJA.

This said one question remains. Recently DRF has added OpenAPI schema support and within DJA we added support for it since version 4.0.0. How is drf-yasg different to this?

I converted the issue to a discussion as this could go different direction and we can always create several issues/work items out of the discussion.

[auvipy]

we should focus on openAPI 3.1 as it is also conforming with json-schema and json-api 1.1! no openAPI 2.0 please

[sliverc]

@glowka Finally got around to define a clear policy on 3rdParty packages and also add a spot to highlight existing packages in our documentation. To start with, I have added drf-yasg-json-api there. Thanks a lot for working on this. This is awesome.

See #1097 for more details.