How to Install Swagger and ReDoc in Django for API Documentation

API documentation is a crucial part of any web application, especially when you're building RESTful APIs. It helps developers understand how to interact with your API, what endpoints are available, and what parameters are required. Swagger and ReDoc are two popular tools for generating interactive API documentation. In this blog post, we'll walk you through the steps to install and configure Swagger and ReDoc in a Django project.

Prerequisites

Before we begin, make sure you have the following installed:

• Python 3.x

• Django (3.x or later)

• Django REST Framework (DRF)

If you haven't set up Django and DRF yet, you can install them using pip:

pip install django djangorestframework

Step 1: Install drf-yasg for Swagger Documentation

drf-yasg is a popular Django package that automatically generates Swagger/OpenAPI 2.0 documentation for your Django REST Framework APIs.

Install drf-yasg

You can install drf-yasg using pip:

pip install drf-yasg

Configure drf-yasg in Your Django Project

1. Add drf_yasg to your INSTALLED_APPS:

   Open your settings.py file and add 'drf_yasg' to the INSTALLED_APPS list:

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

2. Configure URLs for Swagger and ReDoc:

Open your urls.py file and add the following code to set up the Swagger and ReDoc views:

from django.urls import path, include
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
   openapi.Info(
      title="Your API",
      default_version='v1',
      description="API description",
      terms_of_service="https://www.yourapp.com/terms/",
      contact=openapi.Contact(email="contact@yourapp.com"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    ...
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    ...
]

1. • schema_view.with_ui('swagger', cache_timeout=0) generates the Swagger UI.

   • schema_view.with_ui('redoc', cache_timeout=0) generates the ReDoc UI.

     3. Run the Development Server:

     Start your Django development server:

     python manage.py runserver

               Now, you can access the Swagger UI at http://127.0.0.1:8000/swagger/ and the ReDoc UI at http://127.0.0.1:8000/redoc/.

Step 2: Customize Swagger and ReDoc (Optional)

You can customize the appearance and behavior of Swagger and ReDoc by modifying the schema_view configuration. For example, you can change the API title, description, version, and more.

Example Customization:

schema_view = get_schema_view(
   openapi.Info(
      title="My Awesome API",
      default_version='v1',
      description="This is a sample API for demonstration purposes.",
      terms_of_service="https://www.yourapp.com/terms/",
      contact=openapi.Contact(email="support@yourapp.com"),
      license=openapi.License(name="MIT License"),
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),
)

Step 3: Document Your API Endpoints

To make the most out of Swagger and ReDoc, you should document your API endpoints using Django REST Framework's built-in documentation features. You can use docstrings, @swagger_auto_schema decorators, and other tools provided by drf-yasg to add detailed descriptions, request/response examples, and more.

Example of Documenting an API Endpoint:

from drf_yasg.utils import swagger_auto_schema
from rest_framework.response import Response
from rest_framework.views import APIView

class MyAPIView(APIView):
    @swagger_auto_schema(
        operation_description="Get a list of items",
        responses={200: 'List of items'}
    )
    def get(self, request):
        items = ["item1", "item2", "item3"]
        return Response(items)

Conclusion

In this blog post, we've covered how to install and configure Swagger and ReDoc in a Django project using the drf-yasg package. These tools make it easy to generate interactive API documentation, which is essential for both internal development and external API consumers. With Swagger and ReDoc, you can provide a clear and user-friendly interface for exploring your API, making it easier for developers to understand and use your endpoints.

Happy coding! 🚀