Documenting Django Rest Framework API
Tags: django, djangorestframework, swagger, openapi
Published: 2021-01-19 11:38:37

---
title: Documenting Django Rest Framework API
published: True
tags:
  - "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/](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

```python
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

```python
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,

```python
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>