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],
)
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
Top comments (0)