To document a Django REST Framework API in 2026, install drf-spectacular, set it as your DEFAULT_SCHEMA_CLASS, and expose an OpenAPI 3 schema with Swagger UI and ReDoc — do not use django-rest-swagger, which has been deprecated and archived since 2019.
If you arrived here searching for "Django REST Swagger", you are in the right place but the tool has changed. The original django-rest-swagger package is unmaintained, and Django REST Framework's own built-in CoreAPI schema generation (rest_framework.schemas) was deprecated and later removed. Both produced OpenAPI 2 (Swagger 2) documents that often drifted out of sync with the real API. The modern, accurate replacement is drf-spectacular, which inspects your serializers and views to emit a valid OpenAPI 3.x schema and ships interactive Swagger UI and ReDoc out of the box.
Key takeaways
django-rest-swaggeris deprecated and archived — do not start new projects with it, and migrate existing ones.- DRF's built-in CoreAPI schema generation was also deprecated and removed; it is no longer a viable path.
- drf-spectacular is the recommended tool: it produces OpenAPI 3.x and serves both Swagger UI and ReDoc.
- drf-yasg still works but is limited to OpenAPI 2 (Swagger 2) — only choose it if a downstream tool requires Swagger 2.
- Setup is three steps: install, set
DEFAULT_SCHEMA_CLASS, and wire up the schema + UI URLs. - Use the
@extend_schemadecorator to fine-tune summaries, parameters, and responses per view.
Why is django-rest-swagger deprecated?
django-rest-swagger was the go-to documentation package for Django REST Framework years ago, but its repository has been archived and read-only since around 2019 and receives no fixes or updates. It depended on the older CoreAPI ecosystem and emitted Swagger 2 / OpenAPI 2 documents.
Around the same time, Django REST Framework deprecated its built-in CoreAPI schema generation (the rest_framework.schemas / get_schema_view CoreAPI path) and steered users toward OpenAPI 3. That CoreAPI machinery was subsequently removed, so any tutorial that tells you to add 'rest_framework_swagger' to INSTALLED_APPS or call schemas.SchemaGenerator is out of date and will not work on a current stack.
The practical problems with the legacy approach were that the generated schema was frequently inaccurate — request/response bodies, types, and enums often did not match the real endpoints — and it was stuck on an older spec version that modern API tooling is steadily dropping. OpenAPI 3, generated by drf-spectacular, fixes both issues.
drf-spectacular vs drf-yasg vs django-rest-swagger
Here is how the current options compare, so you can pick the right one before writing any code:
| Tool | OpenAPI version | Maintained? | Swagger UI / ReDoc | Schema accuracy | Recommendation |
|---|---|---|---|---|---|
| drf-spectacular | OpenAPI 3.x | Yes — actively maintained | Both, built in | High — inspects serializers, types, enums | Recommended for new and existing projects |
| drf-yasg | OpenAPI 2 (Swagger 2) | Yes, but OpenAPI 2 only | Swagger UI + ReDoc | Good, but capped at the older spec | Only if a downstream tool requires Swagger 2 |
| django-rest-swagger | OpenAPI 2 (via CoreAPI) | No — archived since ~2019 | Swagger UI only | Low — CoreAPI-based, drifts easily | Do not use — deprecated |
| DRF built-in CoreAPI schema | CoreAPI / OpenAPI 2 | No — removed from DRF | N/A | Low | Removed — do not use |
For almost everyone, the answer is drf-spectacular. Reach for drf-yasg only when an external consumer is locked to Swagger 2. Treat django-rest-swagger and the old CoreAPI schema purely as something to migrate away from.
How do you document a Django REST API in 2026?
Documenting your API with drf-spectacular takes three short steps plus optional per-view tuning. This assumes you already have a working DRF project; if you are just getting started, see our introduction to API development with Django REST Framework.
Step 1: Install drf-spectacular
Install the package into your project's virtual environment:
pip install drf-spectacularStep 2: Configure settings.py
Add drf_spectacular to INSTALLED_APPS, point DRF's DEFAULT_SCHEMA_CLASS at it, and describe your API with SPECTACULAR_SETTINGS. The schema is generated from your serializers and views, so accurate Django serializers directly translate into accurate documentation.
# settings.py
INSTALLED_APPS = [
# ...
"rest_framework",
"drf_spectacular",
]
REST_FRAMEWORK = {
"DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}
SPECTACULAR_SETTINGS = {
"TITLE": "My Project API",
"DESCRIPTION": "Public REST API for My Project.",
"VERSION": "1.0.0",
# Keep the raw schema out of the Swagger UI HTML response.
"SERVE_INCLUDE_SCHEMA": False,
}Step 3: Wire up the schema and UI URLs
Expose three routes: the raw OpenAPI 3 schema, the interactive Swagger UI, and the ReDoc reference. If you organise your endpoints with DRF routers and viewsets, they are picked up automatically — no manual listing required.
# urls.py
from django.urls import path
from drf_spectacular.views import (
SpectacularAPIView,
SpectacularSwaggerView,
SpectacularRedocView,
)
urlpatterns = [
# Raw OpenAPI 3 schema (YAML by default).
path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
# Interactive Swagger UI.
path(
"api/docs/",
SpectacularSwaggerView.as_view(url_name="schema"),
name="swagger-ui",
),
# ReDoc reference docs.
path(
"api/redoc/",
SpectacularRedocView.as_view(url_name="schema"),
name="redoc",
),
]Restart the dev server and visit /api/docs/ for Swagger UI or /api/redoc/ for ReDoc. The legacy @api_view + OpenAPIRenderer / SwaggerUIRenderer pattern from django-rest-swagger is no longer needed — drf-spectacular's views replace it entirely.
Step 4: Annotate views with @extend_schema
drf-spectacular reads most of what it needs automatically, but you can refine any endpoint with the @extend_schema decorator — add summaries, document query parameters, and pin response serializers. This works on APIView, viewsets, and function-based or class-based views alike.
# views.py
from drf_spectacular.utils import extend_schema, OpenApiParameter
from rest_framework import viewsets
from .models import Article
from .serializers import ArticleSerializer
class ArticleViewSet(viewsets.ModelViewSet):
queryset = Article.objects.all()
serializer_class = ArticleSerializer
@extend_schema(
summary="List published articles",
description="Returns a paginated list of published articles.",
parameters=[
OpenApiParameter(
name="tag",
description="Filter results by tag slug.",
required=False,
type=str,
),
],
responses=ArticleSerializer,
)
def list(self, request, *args, **kwargs):
return super().list(request, *args, **kwargs)Generating a static schema file
For CI checks, client SDK generation, or publishing the contract to a gateway, export the schema to a file with the management command drf-spectacular registers:
./manage.py spectacular --color --file schema.ymlCommit schema.yml and validate it in CI so the documentation can never silently drift from the implementation. You can then feed that file to OpenAPI client generators to produce typed SDKs for your frontend or mobile teams.
Need a production-grade, fully documented API without the trial and error? Our team builds and modernises DRF backends every week — explore our Django development services to get an OpenAPI 3 contract, Swagger UI, and a clean migration off legacy tooling.
Frequently Asked Questions
Is django-rest-swagger still maintained in 2026?
No. The django-rest-swagger package has been archived and unmaintained since around 2019 and receives no security or compatibility fixes. It generates older OpenAPI 2 (Swagger 2) documents through the deprecated CoreAPI system. For any current Django REST Framework project you should use drf-spectacular instead.
What is the best tool to document a Django REST Framework API?
drf-spectacular is the recommended choice in 2026. It generates a valid OpenAPI 3.x schema directly from your serializers and views, and it serves both Swagger UI and ReDoc out of the box. It is actively maintained and produces a more accurate schema than the legacy django-rest-swagger or DRF's removed CoreAPI generator.
What is the difference between drf-spectacular and drf-yasg?
The key difference is the spec version. drf-spectacular targets OpenAPI 3.x, while drf-yasg is limited to OpenAPI 2 (Swagger 2). Both are maintained and both serve Swagger UI and ReDoc, but new projects should prefer drf-spectacular for OpenAPI 3 support. Choose drf-yasg only when a downstream consumer is locked to Swagger 2.
Does drf-spectacular support both Swagger UI and ReDoc?
Yes. drf-spectacular ships dedicated views — SpectacularSwaggerView for Swagger UI and SpectacularRedocView for ReDoc — that both render from the same SpectacularAPIView schema endpoint. You wire all three as normal Django URL patterns, so you can offer interactive Swagger UI and polished ReDoc reference docs from one source of truth.
How do I customise the documentation for a specific view?
Use the @extend_schema decorator from drf_spectacular.utils on the view or viewset method. It lets you set a summary and description, document query and path parameters with OpenApiParameter, override request and response serializers, and add examples. This is the supported way to refine endpoints that automatic introspection cannot fully describe.
Can I export the OpenAPI schema to a file?
Yes. drf-spectacular registers a management command, so running ./manage.py spectacular --file schema.yml writes the OpenAPI 3 document to disk. This is useful for validating the contract in CI, generating typed client SDKs, or uploading the schema to an API gateway or developer portal.