Django REST Framework Yet Another Swagger Generator (drf-yasg)

1.21.15 · active · verified Thu Apr 09

drf-yasg is a powerful tool for automated generation of real Swagger/OpenAPI 2.0 schemas directly from Django Rest Framework code. It simplifies API documentation by integrating Swagger UI and ReDoc into Django projects. The current version is 1.21.15, and the project maintains an active release cadence with frequent updates and bug fixes.

Warnings

breaking drf-yasg no longer guarantees preservation of schema field order due to a change from `OrderedDict` to native `dict` for schema generation.
Fix: Review any client-side or external tools that strictly rely on the order of fields in the generated OpenAPI schema. Most OpenAPI consumers should not depend on field order, but if specific integrations break, consider custom schema generation or alternative validation.
deprecated Python 3.6 support has been officially dropped. Installations on Python 3.6 may encounter issues or lack new features.
Fix: Upgrade your Python environment to 3.7 or higher. The library officially supports Python 3.9+.
gotcha Issues with `from __future__ import annotations` and complex type hints, especially on Python 3.12, could lead to schema generation failures.
Fix: Ensure you are on drf-yasg 1.21.15 or newer, which includes fixes for Python 3.12 type parameter syntax. For older versions or other type hint issues, review your type hint usage or consider temporarily disabling `from __future__ import annotations` if possible.
gotcha When using `django-filter`, filter parameters might not appear in the generated Swagger UI if the drf-yasg version is too old.
Fix: Upgrade drf-yasg to 1.21.11 or higher, which includes a fix for `django-filter>=25` compatibility.
deprecated The `drf_yasg.inspectors.coreapi.CoreAPICompatInspector` has been replaced by `drf_yasg.inspectors.query.DrfAPICompatInspector`.
Fix: If you were using custom inspectors based on `CoreAPICompatInspector`, update your configuration to use `DrfAPICompatInspector` for improved compatibility and future-proofing.

Install

pip install drf-yasg Install drf-yasg

Imports

get_schema_view

from drf_yasg.views import get_schema_view

openapi
```
from drf_yasg import openapi
```

swagger_auto_schema

from drf_yasg.utils import swagger_auto_schema

path
```
from django.urls import path
```
While `url` might still work in some Django versions, `path` from `django.urls` is the modern and recommended approach for defining URL patterns in Django 2.0+.

Quickstart

To quickly integrate drf-yasg, add 'drf_yasg' to your `INSTALLED_APPS` in `settings.py`. Then, include these URL patterns in your project's `urls.py`. This setup provides endpoints for the OpenAPI schema in JSON/YAML, the interactive Swagger UI, and the ReDoc documentation.

from django.urls import path, re_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="My API",
      default_version='v1',
      description="Test description",
      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 = [
   re_path(r'^swagger(?P<format>\.json|\.yaml)$', 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'),
]

view raw JSON →