drf-spectacular

drf-spectacular generates OpenAPI schemas directly from a Django REST Framework project’s serializers, views, and viewsets, going well beyond DRF’s built-in schema generator. It started as a heavily modified fork of DRF’s native OpenAPI generator, built specifically to extract more accurate schema information automatically, stay usable on real-world (not toy) APIs, and produce output that works cleanly with popular client-code generators like openapi-generator and Swagger Codegen.

The library covers the parts of API documentation that are otherwise painful to keep accurate by hand: nested/recursive serializer components, polymorphic responses, authentication scheme detection, i18n, request/response examples, and built-in extension points for a long list of common DRF add-ons (SimpleJWT, django-filter, django-oauth-toolkit, django-polymorphic, drf-nested-routers, Pydantic, and more).

What You Get

• Automatic OpenAPI 3.0.3 / 3.1 / 3.2 schema generation from DRF serializers, views, viewsets, and function-based views
• @extend_schema and @extend_schema_field decorators to override or augment inferred schema details (parameters, request/response bodies, examples, polymorphic responses)
• Built-in SpectacularAPIView, Swagger UI, and Redoc views for serving and browsing the generated schema
• Authentication scheme detection for DRF-native auth plus SimpleJWT, OAuth Toolkit, dj-rest-auth, and others out of the box
• First-class integrations for django-filter, drf-nested-routers, django-polymorphic, Pydantic (>=2.0), and django-rest-framework-gis
• Vendor extension (x-*) support across info, operations, parameters, components, and security schemes, plus i18n and sane operation_id naming

Common Use Cases

• Generating an always-in-sync OpenAPI spec for a DRF API instead of hand-maintaining Swagger/YAML files
• Serving interactive Swagger UI or Redoc documentation directly from a Django app with no extra infrastructure
• Feeding a generated schema into client-code generators (TypeScript, Java, etc.) to produce typed API clients
• Documenting polymorphic or deeply nested serializer responses that DRF’s built-in schema generator can’t express
• Auditing an API’s authentication and permission surface via the generated security schemes

Under The Hood

Architecture — The package is organized as a Django app (drf_spectacular/) with generators.py performing the core schema-building walk over a DRF Router/APIView set, openapi.py assembling the resulting OpenAPI document, and plumbing.py/utils.py housing the serializer/field introspection helpers that turn DRF component types into OpenAPI schema fragments. extensions.py implements an extension-point system (OpenApiSerializerExtension, OpenApiAuthenticationExtension, etc.) that the contrib/ package uses to register first-class support for third-party libraries (SimpleJWT, django-filter, Pydantic, django-oauth-toolkit) without touching the core generator. views.py/renderers.py expose the schema and Swagger/Redoc UI as ordinary DRF views.

Tech Stack — Pure Python, built against Django and Django REST Framework, packaged with a standard pyproject.toml/setup.cfg, using PyYAML/uritemplate/jsonschema as core runtime dependencies and an extensive requirements/ directory of optional dependencies for each contrib integration it supports.

Code Quality — The tests/ directory is large and organized by feature area (test_basic.py, test_callbacks_split_request.yml, a dedicated tests/contrib/ suite per third-party integration, and both OAS 3.0 and 3.1 golden-file fixtures), run via runtests.py/tox.ini across multiple Django/DRF version combinations, with Codecov coverage tracking. The project ships a py.typed marker and has years of continuous, active maintenance (drf-spectacular is the de facto standard OpenAPI generator for DRF, having effectively superseded drf-yasg).

API Design — Zero-config usage works for straightforward serializers (add it to INSTALLED_APPS, point DEFAULT_SCHEMA_CLASS at it, done), while the @extend_schema decorator gives an escape hatch for every case introspection can’t resolve alone — extra parameters, response overrides per status code, polymorphic responses, and per-field type hints via @extend_schema_field. The contrib/ extension mechanism means adopting a supported third-party library (SimpleJWT, django-filter) requires no manual schema code at all, which keeps the common path close to zero-boilerplate despite the underlying introspection being substantial.