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
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.
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.
Related
Trying to implement wrapper for existing REST APIS using Django graphQL.
Found similar one in JS but not in Django.
https://graphql.org/blog/rest-api-graphql-wrapper/
Could anyone please suggest if there is a GraphQL Django wrapper for REST calls. Haven't found in documentation either
Are you talking about a rest API using DRF? I'd suggest you look at graphene-django-cud to help you with mutations. Graphene-django is required for this, and will help with your queries. Unfortunately it's not a wrapper that will convert all your DRF code into graphql, however you should be able to basically copy paste a lot of the content in your serializers/views.
I'm considering using GraphQL with a Django backend service but I couldn't find much information regarding the API documentation. I need some solution to dynamically generate the documentation, perhaps like npm's graphql-docs with a result similar to GitHub's API docs.
Is it feasible to accomplish with graphene-django? If not, what's a good alternative for a python environment?
Yes, it's very easy to do by using GraphiQL, which is embedded in to Graphene.
The instructions on how to integrate this with Graphene are here in the graphene-python documentation. --- basically you need to add the parameter graphiql=True when setting up the API route in your urls.py file.
After it is set up, if go to your API endpoint in your browser, you'll see a nice interface for sending API calls, getting API responses, and reading documentation for both queries and mutations. The documentation is initially hidden on the right until you click on the "< Docs" link.
It might be a silly question for many, but why can't I instead
Create a view in django that takes a request and returns HttpResponse in, say, JSON format
Map the view to a URL
Hit the URL from my browser or another server and use the result?
Thanks.
EDIT - Two approaches: Import some djangorestframework or tastypie and build an api in my application which will throw json responses VS building a view and tell it to return json response. Is there any huge advantage of using the first one?
I think you could make the same argument about any extension library. It just depends on how much you want to rebuild and what the existing library has that would be beneficial to your project.
Many times I've created custom endpoints without an API library when working with ajax requests inside my project. For that instance, using an API package is overkill. But for having a full API server, Django rest framework offers a lot of functionality.
Sure, you can make views that do what you suggested. But at some point are you going to want to authenticate through an HTTP request? Are you going to want to filter? Are you going to want to make permissions, or just have all endpoints open? Are you going to want to protect against CORS?
You can kind of go down the list of all the features of an API library and ask these questions about what you want to accomplish with your project. If you're working with any type of external application and your django project is just for an API server, usually it's best to go with Rest Framework. If you just have some one-off endpoints to receive ajax requests, usually you just want to build custom endpoints.
I'm new to Facebook development. I'm working on migrating an existing app in accordance to the Graph API upgrade guide. I'm looking for guidance around calls such as api.facebook.com/method/Fql.multiquery.
My question is: does this type of API need to be upgraded as well, or does it only apply to graph.facebook.com calls? I want to ensure that api.facebook.com/method/Fql.multiquery calls will still work after 4/30/15.
You may want to take a look at the Batch Requests of the Graph API. You can also specify dependencies between the requests.
Calls to http://api.facebook.com/method/Fql.multiquery will no longer work. The REST API is long deprecated anyway.
As #luschn said, you have to migrate to the Graph APIs batch requests, and use the /fql endpoint. You can only use FQL if you have a v2.0 app, and not higher.
Mashery iodocs is a tool for documenting API. It needs two configuration json objects to run. It would be nice to have this objects generated automatically by tastypie. Tastypie can generate json with schema, however it's incompatible with iodocs expectations. Any ideas of how to generate this configurtion automatically using tastypie?
Presently, I do not believe there is a way to generate that kind of documentation from TastyPie directly. However, I have found this project useful in creating interactive API documentation.
https://github.com/Hipo/Django-API-Playground
One more project to generate documentation automatically - https://github.com/minism/django-tastypie-swagger
Though so far I haven't find anything convincing!