Generate swagger doc for your django Project using drf_yasg

Why do we need API documentation and what is swagger?

API documentation is used to provide details about how to use and integrate with an API by providing information on the requests (including parameters to be passed, headers, authorization etc) and the responses of the API.

It becomes really important when you are working on a project which has a large number of APIs and you want to expose it to external teams (or your clients) who have no/little idea of your APIs’ functionality, which API is meant to fetch or post what.

Swagger and redoc are open-source tools that auto generate API documentation from OpenAPI specifications(API description format for REST APIs).

Why choose drf_yasg?

drf_yasg or Yet Another Swagger Generator is a API doc generation tool which provides the option to choose between swagger-ui and redoc or both for generating documentation for your APIs

Getting started with drf_yasg

To give an illustration of how to use drf_yasg to generate Swagger docs for APIs, I have created a simple project called Showroom.

The project is available here:

https://github.com/ChayanikaMisra/swagger-example

The Showroom project has two models, Showroom and Car. Each car is mapped to a showroom id (foreign key relationship).

The project exposes an API to return the showroom details along with the details of the cars present in that showroom given a car id as the query parameter.

Lets get started with the API doc using drf_yasg.

Step 1: Adding drf-yasg to your project

Install drf-yasg

pip install drf-yasg

Add it to the requirements.txt file

djangorestframework==3.11.1drf-yasg==1.17.1

Add it to your INSTALLED_APPS in settings.py

INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_yasg',
    ...
]

Step 2:

Define a schema_view using get_schema_view(This is where the configuration for the swagger goes) in urls.py

schema_view = get_schema_view(
    openapi.Info(
        #  add your swagger doc title
        title="Showroom API",
        #  version of the swagger doc
        default_version='v1',
        # first line that appears on the top of the doc
        description="Test description",
    ),
    public=True,
)

Add a swagger URL to your projects urls.py

url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui')

Step 3:

Hit the url <root_url>/swagger/ and its ready!!

This is my first ever tech write up. Hope it has helped you in some way. Looking forward to receiving any kind of feedback.

For any queries, reach me at chayanikamisra1997@gmail.com

Thank you!!