Documenting 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 INSTALLED_APPS 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],
)

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"
),

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)

• 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