Comprehensive approach to django-rest-swagger 2 using both FBV and CBV

This project provides a beginner's guide to django rest swagger 2 with function based views as well as class based views. It provides building the project from scratch. For those who want to integrate Django Rest Swagger into an existing project, head straight to: Integrating Django Rest Swagger .

Read this article on Medium if that is more convenient for you.

Getting Started

Before we start, we need this to be installed:

• Python3

Project Setup

Start by making the project as in DRF official docs:

mkdir django-rest-swagger-docs
cd django-rest-swagger-docs

Make virtual environment with python3 and activate it:

virtualenv env --python=python3
source ./env/bin/activate

Install Django and DjangoRestFramework:

pip install django
pip install djangorestframework==3.5.3

Note: Installing the correct version of DRF is very important.

Make project named demo in current directory and navigate inside it:

django-admin startproject demo .
cd demo

Make two apps cbv-demo (for class based views) and fbv-demo (for function based view) inside demo project,:

django-admin startapp cbv_demo
django-admin startapp fbv_demo

Get back to main directory:

cd ..

Now sync database and create database user:

python manage.py migrate
python manage.py createsuperuser

Making class based views:

Make a simple model at demo/cbv_demo/models.py with code below:

from django.db import models


class Contact(models.Model):
    name = models.CharField(max_length=22)
    phone = models.CharField(max_length=22)
    address = models.CharField(max_length=44)

Make a simple serializer at demo/cbv_demo/serializers.py with code below:

from rest_framework import serializers
from .models import Contact


class ContactDataSerializer(serializers.ModelSerializer):
    class Meta:
        model = Contact
        fields = '__all__'

Make a simple view at demo/cbv_demo/views.py with code below:

from demo.cbv_demo.serializers import ContactDataSerializer
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated
from .models import Contact
from rest_framework import status , generics


class ContactData(generics.GenericAPIView):
    serializer_class = ContactDataSerializer
    permission_classes = [IsAuthenticated,]

    def get(self, request, format=None):
        contacts = Contact.objects.all()
        serializer = ContactDataSerializer(contacts, many=True)
        return Response(serializer.data)

    def post(self, request, format=None):
        serializer = ContactDataSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)

        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

Add urls of this app to demo/cbv_demo/urls.py as:

from django.conf.urls import url
from .views import ContactData


urlpatterns = [
    url(r'^contact', ContactData.as_view(), name='contact'),
]

Making function based views:

Make a simple model at demo/fbv_demo/models.py with code below:

from django.db import models


class Medical(models.Model):
    name = models.CharField(max_length=22)
    bloodgroup = models.CharField(max_length=22)
    birthmark = models.CharField(max_length=44)

Make a simple view at demo/fbv_demo/views.py with code below:

from rest_framework.decorators import api_view
from rest_framework.response import Response
from .models import Medical
from rest_framework import status


@api_view(['POST'])
def save_medical(request):
    name = request.POST.get('name')
    bloodgroup = request.POST.get('bloodgroup')
    birthmark = request.POST.get('birthmark')

    try:
        Medical.objects.create(name= name, bloodgroup = bloodgroup, birthmark = birthmark)
        return Response("Data Saved!", status=status.HTTP_201_CREATED)

    except Exception as ex:
        return Response(ex, status=status.HTTP_400_BAD_REQUEST)


@api_view(['GET'])
def get_medical(request):
    return Response(Medical.objects.all().values(), status=status.HTTP_200_OK)

Add urls of this app to demo/fbv_demo/urls.py as:

from django.conf.urls import url
from .views import save_medical, get_medical


urlpatterns = [
    url(r'^save_medical', save_medical, name='save_contact'),
    url(r'^get_medical', get_medical, name='get_contact'),
]

Add 'rest_framework' and both apps to demo/settings.py as:

INSTALLED_APPS = [
    ...
    'rest_framework',
    'demo.cbv_demo',
    'demo.fbv_demo',
]

Now add urls of both apps to demo/urls.py:

from django.conf.urls import url, include


urlpatterns = [
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    url(r'^cbv/', include('demo.cbv_demo.urls')),
    url(r'^fbv/', include('demo.fbv_demo.urls')),
]

Now you have class based views (GET, POST) in demo/cbv_demo/views.py and two function based views in demo/fbv_demo/views.py .

In order to run the it apply migrations to make tables in db against models and runserver to test:

python manage.py makemigrations
python manage.py migrate
python manage.py runserver

Integrating Django Rest Swagger:

In order to integrate django-rest-swagger, first install it through pip as:

pip install django-rest-swagger==2.1.1

Note: Installing the correct version is very important.(This one works best with djangorestframework==3.5.3)

Add it into the demo/settings.py as:

INSTALLED_APPS = [
    ...
    'rest_framework_swagger',
]

# Parser classes to help swagger, default ll be JSONParser only.

REST_FRAMEWORK = {
    # Parser classes priority-wise for Swagger
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework.parsers.FormParser',
        'rest_framework.parsers.MultiPartParser',
        'rest_framework.parsers.JSONParser',
    ],
}

Using get_swagger_view the shortcut method:

Make swagger schema view in demo/urls.py and assign it a url as :

from rest_framework_swagger.views import get_swagger_view
schema_view = get_swagger_view(title='Demo Swagger API')


urlpatterns = [
    ...
    url(r'^swagger/', schema_view),
]

Your swagger should run at: http://127.0.0.1:8000/swagger/

Using shortcut method can let us into following issues:

• No way to document parameters of function based views
• Less customizablity
• No way to enforce permission classes
• No handy way to exclude swagger view from schema

In order to acheive these functionalities, we ll go for its advance usage.

Advance Usage:

For finer control and to make swagger more customizable we write swagger schema view manually and to document parameters for function based views, we override SchemaGenerator of rest_framework which is used by django-rest-swagger (version 2) to generate documentation.

Create a file demo/swagger_schema.py and add following code to it:

from rest_framework.permissions import AllowAny
from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework_swagger import renderers
from rest_framework.schemas import SchemaGenerator
from urllib.parse import urljoin
import yaml
import coreapi


class CustomSchemaGenerator(SchemaGenerator):
    def get_link(self, path, method, view):
        fields = self.get_path_fields(path, method, view)
        yaml_doc = None
        if view and view.__doc__:
            try:
                yaml_doc = yaml.load(view.__doc__)
            except:
                yaml_doc = None

        #Extract schema information from yaml

        if yaml_doc and type(yaml_doc) != str:
            _method_desc = yaml_doc.get('description', '')
            params = yaml_doc.get('parameters', [])

            for i in params:
                _name = i.get('name')
                _desc = i.get('description')
                _required = i.get('required', False)
                _type = i.get('type', 'string')
                _location = i.get('location', 'form')
                field = coreapi.Field(
                    name=_name,
                    location=_location,
                    required=_required,
                    description=_desc,
                    type=_type
                )
                fields.append(field)
        else:

            _method_desc = view.__doc__ if view and view.__doc__ else ''
            fields += self.get_serializer_fields(path, method, view)

        fields += self.get_pagination_fields(path, method, view)
        fields += self.get_filter_fields(path, method, view)

        if fields and any([field.location in ('form', 'body') for field in fields]):
            encoding = self.get_encoding(path, method, view)
        else:
            encoding = None

        if self.url and path.startswith('/'):
            path = path[1:]

        return coreapi.Link(
            url=urljoin(self.url, path),
            action=method.lower(),
            encoding=encoding,
            fields=fields,
            description=_method_desc
        )


class SwaggerSchemaView(APIView):
    exclude_from_schema = True
    permission_classes = [AllowAny]
    renderer_classes = [
        renderers.OpenAPIRenderer,
        renderers.SwaggerUIRenderer
    ]

    def get(self, request):
        generator = CustomSchemaGenerator()
        schema = generator.get_schema(request=request)
        return Response(schema)

exclude_from_schema = True removes the swagger view from schema.

CustomSchemaGenerator class overrides the default DRF SchemaGenerator so that it first checks if the view has .__doc__ inside it, if available it uses this YAML to make parameter fields, otherwise it looks for serializers. So in this way we acheive the functionality of Django Rest Swagger (version 1) which supported YAML docstrings as well.

SwaggerSchemaView is the view made for swagger, which calls CustomSchemaGenerator to create the schema instead of default SchemaGenerator.

Now, You ll need to install yaml as:

pip install PyYAML

Next change demo/urls.py to point swagger url to this SwaggerSchemaView as:

from .swagger_schema import SwaggerSchemaView


urlpatterns = [
    ...
    url(r'^swagger/', SwaggerSchemaView.as_view()),
]

Defining parameters in FBV using YAML:

Now add __doc__ to the function based API by adding YAML into it, add following YAML to save_medical in demo/fbv_demo/views.py as:

@api_view(['POST'])
def save_medical(request):
# ----- YAML below for Swagger -----
"""
description: This API deletes/uninstalls a device.
parameters:
  - name: name
    type: string
    required: true
    location: form
  - name: bloodgroup
    type: string
    required: true
    location: form
  - name: birthmark
    type: string
    required: true
    location: form
"""
...
...

Now CustomSchemaGenerator will be able to read this YAML and create input parameters against it accordingly.

Go to swagger url : http://127.0.0.1:8000/swagger/

You will be able to see input parameters fields for save_medical POST API as well.

Customize Swagger UI:

Swagger UI can be customized to some extent, which is sufficient for a normal user, Follow these simple steps:

• Make the file as demo/templates/rest_framework_swagger/index.html and add following code to it:

{% extends "rest_framework_swagger/base.html" %}

{# TO Customizer Swagger UI #}

{% block header %}
    <div id='header' style="background-color: #000000;">
        <div class="swagger-ui-wrap">
            {% load staticfiles %}
            <a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="{% static 'rest_framework_swagger/images/logo_small.png' %}" /><span class="logo__title">swagger</span></a>
            <form id='api_selector'>
                <input id="input_baseUrl" name="baseUrl" type="hidden"/>
                {% if USE_SESSION_AUTH %}
                {% csrf_token %}
                {% if request.user.is_authenticated %}
                <div class="input">
                    {% block user_context_message %}
                    {# Override this block to customize #}
                    Hello, {{ request.user }}
                    {% endblock %}
                </div>
                {% endif %}
                {% block extra_nav %}
                {# Override this block to add more buttons, content to nav bar. #}
                {% endblock %}
                {% endif %}

                {% if USE_SESSION_AUTH %}
                {% if request.user.is_authenticated %}
                <div class='input'><a id="auth" class="header__btn" href="{{ LOGOUT_URL }}?next={{ request.path }}" data-sw-translate>Django Logout</a></div>
                {% else %}
                <div class='input'><a id="auth" class="header__btn" href="{{ LOGIN_URL }}?next={{ request.path }}" data-sw-translate>Django Login</a></div>
                {% endif %}
                {% endif %}
                <div id='auth_container'></div>
            </form>
        </div>
    </div>
{% endblock %}

This will override the tag {% block header %} , for the sample we are just changing the colour of header, rest remains the same.

• Set template directory in demo/settings.py as:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['demo/templates/'],
        ...
    }
]

You ll be able to see custom BLACK header at http://127.0.0.1:8000/swagger/.

Some add-ons that may help:

Django Rest Swagger provide much customization, most of which is explained indepth in its Official Doc .

Few mostly used customization is explained here for ease. Add SWAGGER_SETTINGS in demo/settings.py to provide custom settings:

Swagger Login methods:

You can login to swagger by using button Authorize in the header of swagger UI.

In order to use django superuser username and password to login use:

SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        'basic': {
            'type': 'basic'
        }
    },
}

In order to use authentication token to login to swagger use:

SWAGGER_SETTINGS = {
    'SECURITY_DEFINITIONS': {
        "api_key": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
          },
    },
}

You can use oauth2 for security. Details: security definitions .

DJANGO LOGIN Button:

You can also use Django Login button to login. It uses django admin panel for authentication. In order to make it run correctly you must set LOGIN_URL and LOGOUT_URL in swagger settings. For example if you have rest_framework's login mechanism, you can set:

SWAGGER_SETTINGS = {
    'USE_SESSION_AUTH': True,
    'LOGIN_URL': 'rest_framework:login',
    'LOGOUT_URL': 'rest_framework:logout',
}

If you want to disable this button just set USE_SESSION_AUTH to False.

VALIDATION_URL:

A schema json is generated against APIs which you may like to get validated by swagger.io. Its value can be set to any local deployment of validator. By default it is set to: https://online.swagger.io/validator/. Set it to None to not validate your schema.

SWAGGER_SETTINGS = {
    ...
    
    'VALIDATOR_URL': None,
}

Additionally you can also validate your schema manually by copying your schema json to https://editor.swagger.io/.

Customize format of parameters defined in DOCSTRING:

You can customize YAML parameters, the most important is location that helps you with passing the data to API in different forms.

• location: form , to access data as request.POST['key']

• location: body , to access data as request.body , you may have to add JSON_EDITOR: False in SWAGGER_SETTINGS in demo/settings.py.

• location: query , to access data as request.GET['key']

Other location options include location: post and location: path

Common issues and their solution:

Since the release of version 2 of django-rest-swagger, various issues arise because this version is fundamentally different from previous versions, i.e. DOCSTRING has been deprecated by DRF and now swagger uses DRF 's SchemaGenerator to generate schema.

Here are some of the reported issues and their possible solution:

• The schema generator did not return a schema Document: All the APIs of your project may be authentication protected, try removing authentication from few of them.

• Input parameters for class based views do not appear: You might be using APIView for making class based views. Try using generics.GenericAPIView to make APIs. All the views must have serializer or Docstring __doc__.

• Input parameters for function based views do not appear: You might be using incompatible versions, try using djangorestframework==3.5.3 and django-rest-swagger==2.1.1. In order to use other versions you may need to modify get_link inside demo/swagger_schema.py.

• TypeError: 'type' object is not iterable: Try adding your authentication in this format @permission_classes((IsAuthenticated, )).

• Invalid block tag: 'static', expected 'endblock'. Did you forget to register or load this tag? : Try adding {% load staticfiles %} to the overridden block of swagger UI e.g. add in demo/templates/rest_framework_swagger/index.html as:

{% extends "rest_framework_swagger/base.html" %}
{% block header %}
    <div id='header' style="background-color: #000000;">
        <div class="swagger-ui-wrap">
            {% load staticfiles %}
            ...
            ...
        </div>
    </div>
{% endblock %}

• schemaValidationMessages message:"Can't read from file http://0.0.0.0:8000/swagger/?format=openapi : This error is rendered because you schema validation is enabled in swagger settings but your server is not accessible from external network(which swagger.io tries to access for validation purpose). Try running your server with python manage.py runserver 0.0.0.0:8000 --insecure and in your settings.py add ALLOWED_HOSTS = ['*'] . You wont get this error while accessing server from external network now.

  Success in validation would show:

• schemaValidationMessages message: "instance type () does not match any allowed primitive : This error means that your schema json does not validated by online.swagger.io/validator. You can disable validation by setting "VALIDATION_URL" : None in swagger settings or to fix the issue you can validate your schema better manually by pasting on https://editor.swagger.io/.

  Success in validation would show:

End Note:

This repository is intended to help those who are facing issues using django-rest-swagger 2. If you like this effort, please like and share this with others. If you have any suggestions, comment here or approach me on linkedin , medium, twitter or send me an email to discuss in person. I would love to hear from you.