DEV Community

kamalakannan
kamalakannan

Posted on • Edited on

Documenting Django Rest Framework API

#django #djangorestframework #swagger #openapi

original post in https://skamalakannan.dev/posts/document-django-rest-framework-api/

Django Rest Framework (DRF) is a potent tool to create RESTful services with Django. Though it comes with a friendly UI interface to test API, it does not provide detailed documentation.

This post will go through how to document your DRF APIs using https://github.com/axnsan12/drf-yasg/
package.

drf-yasg is an easily pluggable tool and automatically the DRF APIs.
we will see how to document our various type of APIs,

Installation and configuration

  • we can install drf-yasg through

    pip install -U drf-yasg

  • To add it to our project, we need to add drf_yasg to

     in settings.py - We need to configure the URLs for the API document, and the following code generates the document 
schema_view = get_schema_view( openapi.Info( title="Snippets API", default_version='v1', description="Test description", terms_of_service="https://www.google.com/policies/terms/", contact=openapi.Contact(email="contact@snippets.local"), license=openapi.License(name="BSD License"), ), public=True, permission_classes=[permissions.AllowAny], )
Enter fullscreen mode Exit fullscreen mode

and in urls .py

url( r"^swagger(?P<format>\.json|\.yaml)$", schema_view.without_ui(cache_timeout=0), name="schema-json", ), url( r"^swagger/$", schema_view.with_ui("swagger", cache_timeout=0), name="schema-swagger-ui", ), url( r"^redoc/$", schema_view.with_ui("redoc", cache_timeout=0), name="schema-redoc" ),
Enter fullscreen mode Exit fullscreen mode

we have configured 3 urls for swagger documentations,

  • first one is with our UI, this returns the JSON document for all our APIs.
  • second one renders swagger ui for all APIs.
  • the last returns the api documentation in redoc format.

That's it. We have configured the swagger documentation for our APIS, drf-yasg
We can use the swagger_auto_schema decorator to customize the API document.

it accepts the following parameters,

  • method(s) - HTTP method the API handles; in case of multiple HTTP methods use methods, it's a method
  • operation_summary - brief description of the API
  • request_body - request body it can be a DRF serializer or openapi.schema
  • responses - response from the API similar to request_body; it can be DRF serializer or openapi. schema, we can specify different responses for different HTTP response codes Here the example for adding two numbers drf API, 
from rest_framework.decorators import api_view from rest_framework.response import Response from drf_yasg.utils import swagger_auto_schema from drf_yasg import openapi from rest_framework import status from rest_framework import serializers class NumbersSerializer(serializers.Serializer): x = serializers.IntegerField() y = serializers.IntegerField() @swagger_auto_schema( methods=['POST'], operation_summary="Sum of Two numbers", request_body = NumbersSerializer, responses={ 200: openapi.Schema( type=openapi.TYPE_INTEGER, title="s" ) } ) @api_view(['POST']) def add_two_numbers(request): data = request.data serializer = NumbersSerializer(data=data) if serializer.is_valid(): s = serializer.data['x'] + serializer.data['y'] return Response({'sum': s}, status=status.HTTP_200_OK) return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
Enter fullscreen mode Exit fullscreen mode
  • Schema - helps us specify the object
  • type - defines different kinds of values, array, object, string, number, integer, boolean, and file.
  • title - specify the name of the variable

code sample repo - https://github.com/srkama/drf_swagger_doc

Top comments (0)