Django Swagger and JSON API render issues

Question

Using django-rest-framework-json-api I am able to create API end points that work as described within the documentation. Attempted to provide API documentation using django-rest-swagger is not so easy.

1: Swagger uses media_type = 'application/json' which is not supported in the JSON API. To get around this I created a second render class (renderer_classes) that sub classes the JSON API JSONRenderer and forces the media type.

Now the end point supports application/json and application/vnd.api+json and swagger is happy to render in JSON API document structure. Aware that the generated curl requests have none a standard JSON API header.

2: Swagger has the same issue with the parser. While the work out from issue 1 does work there is a secondary challenge. Swagger renders a flat dictionary of field names which is not JSON API and ultimately is requested by DRF.

Is it possible to get swagger to parse in JSON API? At the moment Swagger is not working for PUT or POST.

djangorestframework-jsonapi==2.2.0
djangorestframework==3.5.4
Django==1.11.2
coreapi==2.3.1
python 3.6

Answer 1

Answering my own question here so that others can gain value from what was learnt. We never found a solution to this issue and we did not have the time available to contribute to this project. In general the project also appears to be struggling, maybe due to people like us not contributing...

An alternative project drf-yasg has now emerged, which did not exist at the time of this original posting. drf-yasg was relatively easy to deploy and solved all of our issues so we have now migrated to this project instead.

So if you a looking for swagger api documentation for JSON API endpoints created within DRF, then I would suggest drf-yasg.

At the time of writing JSON API is not supported out of the box, but there is sample code to get it up and running relatively easily. With this change in place, all of the endpoints will be auto documented.

This Github Gist that contains the code from our app, hope that this helps you out until this feature is fully developed.

Answer 2

As you pointed out in your own answer there is an alternative: drf-yasg. This is great package but does not support JSON API schema out of the box.

That's way you'd even better use drf-yasg-json-api that adds JSON API support to drf-yasg by providing all necessary field inspectors, you just need to slightly extend your SWAGGER_SETTINGS.

Check drf-yasg-json-api Github repo for details.

Disclaimer: I am the author of this package.