5

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
oden
  • 3,461
  • 1
  • 31
  • 33
  • 1
    This sounds like a bug with one of the two projects. Either `django-rest-swagger` looks at the models schema and ignores specifics of the views, or `django-rest-framework-json-api` does not present its views' schemas properly to documentation generators. Or maybe `django-rest-framework` does not even have a way for views to present their schemas to documentation generators. Either way I do not suspect there is a way to work around it without modifying the libraries. – Zeust the Unoobian Apr 19 '19 at 08:42
  • @ZeusttheUnoobian I feel the issue was within `django-rest-swagger` but agree with your comments. – oden Apr 23 '19 at 01:30

2 Answers2

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.

oden
  • 3,461
  • 1
  • 31
  • 33
  • 1
    My experience is that `drf-yasg` is definitely an improvement and solves the mimetype problem, but still renders flat request and response body dictionaries. The only way I found around this was by defining separate (and nested) serializers for each call to replicate the schema of a JSON API call, and telling `drf-yasg` to use those instead of the one the application uses. I am kinda hoping you achieved the same result with less handwork, in which case I am curious how :) – Zeust the Unoobian Apr 24 '19 at 11:16
  • 1
    @ZeusttheUnoobian The developer who dis this work is no longer with us, hence I am not across all of the details. Have added in some more details to the answer, included our sample code. Let me know how you go with it. – oden Apr 26 '19 at 00:30
  • At least on first glance, this looks like more code but less hacky than what I did. I think I like it! This looks like something that could be a project-independent glue library between `djangorestframework-jsonapi` and `drf-yasg` with no to little modification. Kudos! – Zeust the Unoobian May 01 '19 at 09:41
1

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.

glowka
  • 730
  • 4
  • 11