Django Rest Framework API Docs with Swagger & ReDoc

Documenting APIs is crucial for developers and users. Django Rest Framework (DRF) offers tools like Swagger and ReDoc for API documentation. This guide will show you how to integrate them.

Why Use Swagger and ReDoc?

Swagger and ReDoc are popular tools for API documentation. They provide interactive and user-friendly interfaces. This makes it easier to understand and test APIs.

Swagger offers a dynamic UI for exploring API endpoints. ReDoc provides a clean and readable documentation format. Both tools are compatible with DRF.

Setting Up Django Rest Framework

Before integrating Swagger and ReDoc, ensure DRF is installed. Use the following command to install DRF:

pip install djangorestframework

Add rest_framework to your INSTALLED_APPS in settings.py:

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

Installing Swagger and ReDoc

To use Swagger and ReDoc, install the drf-yasg package. It integrates Swagger and ReDoc with DRF. Run the following command:

pip install drf-yasg

Add drf_yasg to your INSTALLED_APPS:

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

Configuring Swagger and ReDoc

Configure Swagger and ReDoc in your urls.py file. Import the necessary modules and add the URLs:

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

schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version='v1',
        description="API documentation for your project",
    ),
    public=True,
)

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'),
]

This setup creates two endpoints: /swagger/ and /redoc/. These endpoints serve the Swagger and ReDoc UIs.

Testing the Documentation

Run your Django development server and visit http://localhost:8000/swagger/. You should see the Swagger UI. It lists all your API endpoints.

Visit http://localhost:8000/redoc/ to see the ReDoc UI. It provides a clean and readable format for your API documentation.

Customizing Documentation

You can customize the documentation by modifying the openapi.Info object. Add more details like contact information or license.

schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version='v1',
        description="API documentation for your project",
        contact=openapi.Contact(email="contact@example.com"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
)

Handling Authentication

If your API uses authentication, configure it in the schema view. This ensures the documentation reflects the authentication requirements.

schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version='v1',
        description="API documentation for your project",
    ),
    public=True,
    permission_classes=[permissions.AllowAny],
)

For more advanced authentication, check out our guide on Secure Django Rest Framework APIs.

Optimizing Performance

Documentation can impact performance. Use caching to reduce the load. Learn more in our guide on Optimizing Django Rest Framework Performance.

Conclusion

Documenting your Django Rest Framework API is essential. Swagger and ReDoc make it easy to create interactive and readable documentation. Follow this guide to set up and customize your API documentation.

For more advanced topics, explore our guides on Custom Django Rest Framework Permissions and Using Django Rest Framework with React or Vue.js.