DRF Spectacular

Warnings

• breaking Pydantic users might see a slightly different schema output due to changes in the serialization method. Review generated schemas carefully after upgrading.
  Fix: After upgrading to 0.28.0+, thoroughly test your API schema generation if you use Pydantic models. Adjust any client-side code that relies on specific Pydantic-derived schema structures.
• breaking With the official support for OpenAPI 3.1 and Pydantic>=2, if you use a custom `postprocess_schema_enums` function, you might need to manually add `postprocess_schema_enum_id_removal` to remove temporary IDs.
  Fix: If you have a custom `postprocess_schema_enums` function, ensure it also calls or manually implements the logic of `postprocess_schema_enum_id_removal` to clean up temporary enum IDs introduced for OpenAPI 3.1 compatibility.
• gotcha Python 3.6 support has been officially removed due to upstream library breakage. Attempts to use drf-spectacular on Python 3.6 will likely fail.
  Fix: Ensure your project is running on Python 3.7 or newer. Upgrade your Python environment if necessary.
• gotcha Versions prior to 0.29.0 contained a memory leak during schema generation, particularly noticeable with large or complex APIs.
  Fix: Upgrade to `drf-spectacular` version `0.29.0` or newer to benefit from the memory leak fix. Regular schema regeneration might be needed to mitigate effects in older versions.
• gotcha For API endpoints that are serializers marked `many=False` but are incorrectly inferred as lists in the OpenAPI schema, the `forced_singular_serializer` helper function is available.
  Fix: Apply the `@extend_schema_serializer(many=False)` decorator or use the `drf_spectacular.utils.forced_singular_serializer` helper around your serializer if it's being misinterpreted as a list endpoint.

Install

• pip install drf-spectacular Install stable version

Imports

• SpectacularAPIView

  from drf_spectacular.views import SpectacularAPIView

  Views are imported from `drf_spectacular.views` module.
• SpectacularSwaggerView

  from drf_spectacular.views import SpectacularSwaggerView

  Views are imported from `drf_spectacular.views` module.
• SpectacularRedocView

  from drf_spectacular.views import SpectacularRedocView

  Views are imported from `drf_spectacular.views` module.
• extend_schema

  from drf_spectacular.utils import extend_schema

  Decorators and utilities are found in `drf_spectacular.utils`.
• OpenApiParameter

  from drf_spectacular.utils import OpenApiParameter

  Decorators and utilities are found in `drf_spectacular.utils`.

Quickstart

To integrate DRF Spectacular, add `drf_spectacular` to your `INSTALLED_APPS` and define `SPECTACULAR_SETTINGS` in your `settings.py`. Then, include the schema and UI views in your `urls.py`. The `SpectacularAPIView` serves the raw OpenAPI schema, while `SpectacularSwaggerView` and `SpectacularRedocView` provide interactive documentation UIs.

import os
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView

# --- In your Django settings.py ---
# INSTALLED_APPS = [
#     # ...
#     'rest_framework',
#     'drf_spectacular',
#     # ...
# ]
#
# SPECTACULAR_SETTINGS = {
#     'TITLE': os.environ.get('DRF_SPECTACULAR_TITLE', 'Your Project API'),
#     'DESCRIPTION': os.environ.get('DRF_SPECTACULAR_DESCRIPTION', 'Your project description'),
#     'VERSION': os.environ.get('DRF_SPECTACULAR_VERSION', '1.0.0'),
#     'SERVE_INCLUDE_SCHEMA': False, # Keep off for production, serve via SpectacularAPIView
#     'SWAGGER_UI_SETTINGS': {
#         'deepLinking': True,
#         'displayRequestDuration': True,
#     },
# }

# --- In your Django urls.py ---
urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    # Optional UI: path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    # Optional UI: path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
    # path('api/', include('your_app.urls')), # Example for your API endpoints
]

# To run a minimal example (requires Django setup)
# from django.conf import settings
# if not settings.configured:
#     settings.configure(
#         INSTALLED_APPS=['django.contrib.auth', 'django.contrib.contenttypes', 'rest_framework', 'drf_spectacular'],
#         SPECTACULAR_SETTINGS={'TITLE': 'Test API'},
#         ROOT_URLCONF=__name__,
#         DEBUG=True
#     )
# This is a runnable snippet illustrating the `urls.py` config for drf-spectacular.