Documenting Django Rest Framework API

Published on

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