Building robust and well-documented REST APIs is essential for modern web development. However, manually documenting APIs can be time-consuming and error-prone. In this tutorial, we'll explore how to automatically generate API documentation using DRF-Swagger in Django. DRF-Swagger simplifies the process by providing interactive and visually appealing documentation for your Django REST Framework APIs

Before we go further

1. You must need a Django project setup and running
2. django-rest-framework configured
3. A Django app(myapp)
4. A ready-made model (Post) for testing
5. A viewset for the Post model

Let's get start with the configuration

1. Installing Required Packages

To begin, ensure you have the necessary packages installed. Run the following command to install drf-yasg:

pip install drf-yasg

2. Configuring URLs and Schema View

In your Django project's urls.py file, include the DRF-Swagger URLs by adding the following code:

from django.urls import include, path
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="REST APIs",
        default_version='v1',
        description="API documentation",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="contact@snippets.local"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    # ...
    # Include DRF-Swagger URLs
    path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    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'),

    # Your API URLs
    path('admin/', admin.site.urls),
    path('apps/', include('myapp.urls')),
]

In the above code snippet, you can customize the title, description, and other attributes of your API documentation by modifying the openapi.Info parameters. Adjust them to match your project's details

3. Register swagger in INSTALLED_APPS

INSTALLED_APPS = [
    # ...
    'django.contrib.staticfiles',
    'rest_framework',
    'drf_yasg',
    'myapp',
]

This exposes 4 endpoints:

• A JSON view of your API specification at /swagger.json
• A YAML view of your API specification at /swagger.yaml
• A swagger-ui view of your API specification at /swagger/
• A ReDoc view of your API specification at /redoc/

4. Generating API Documentation

With DRF-Swagger properly configured, start your Django development server and access the provided URLs for the Swagger UI and ReDoc interfaces. Explore the generated API documentation, interact with endpoints, and view response schemas directly from the interface

Go to the browser and type http://localhost:8000/swagger. You'll see Swagger UI to test your APIs

API documentation plays a crucial role in facilitating API consumption and development. By leveraging DRF-Swagger in Django, you can automate the process of generating comprehensive and interactive documentation for your RESTful APIs. This saves time, reduces errors, and improves collaboration among team members. Take advantage of DRF-Swagger's features to create robust and easily accessible documentation for your Django REST Framework projects

Find the complete project here

Thank you for reading. Support me by clapping and sharing this blog

Let's catchup in LinkedIn