How to Use Swagger with Django REST Framework (DRF)

To use Swagger with Django REST Framework (DRF), install the drf-yasg package, add it to your INSTALLED_APPS, and configure URL patterns to serve the Swagger UI. This setup automatically generates interactive API docs from your DRF views and serializers.

Syntax

Here is the basic syntax to add Swagger UI using drf-yasg in your Django project:

• Import get_schema_view and openapi from drf_yasg.
• Define a schema_view with API info like title and version.
• Add URL patterns for Swagger UI and ReDoc views.

python

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

schema_view = get_schema_view(
    openapi.Info(
        title="Your API",
        default_version='v1',
        description="API documentation",
    ),
    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'),
]

Example

This example shows a minimal Django project setup with DRF and Swagger UI using drf-yasg. It includes a simple API view and the Swagger documentation URLs.

python

from django.urls import path
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

from drf_yasg.views import get_schema_view
from drf_yasg import openapi
from rest_framework import permissions

class HelloWorld(APIView):
    def get(self, request):
        return Response({"message": "Hello, world!"}, status=status.HTTP_200_OK)

schema_view = get_schema_view(
    openapi.Info(
        title="Sample API",
        default_version='v1',
        description="Test API for Swagger with DRF",
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    path('hello/', HelloWorld.as_view(), name='hello-world'),
    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'),
]

Output

When running the Django server and visiting /swagger/, you see an interactive Swagger UI showing the /hello/ GET endpoint with its response schema.

Common Pitfalls

Common mistakes when using Swagger with DRF include:

• Not installing or adding drf-yasg to INSTALLED_APPS.
• Forgetting to import path from django.urls in urls.py.
• Not setting permission_classes properly, which can block access to the docs.
• Using old or incompatible versions of drf-yasg with your Django or DRF version.

Example of a wrong URL pattern missing path import:

python

from django.urls import re_path  # Wrong if you use path but forgot to import it

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

Quick Reference

Summary tips for using Swagger with DRF:

• Install drf-yasg via pip install drf-yasg.
• Add 'drf_yasg' to INSTALLED_APPS in settings.py.
• Use get_schema_view to create schema views.
• Add URL routes for Swagger UI and ReDoc.
• Ensure your API views have proper serializers and docstrings for best docs.

Key Takeaways

Install and add drf-yasg to your Django project to enable Swagger UI with DRF.

Configure schema views and URL patterns to serve interactive API documentation.

Ensure permission classes allow public access to the Swagger docs during development.

Keep drf-yasg and Django REST Framework versions compatible to avoid errors.

Use clear serializers and view docstrings for better auto-generated documentation.