In Django REST Framework 3.18, what is the status of built-in OpenAPI schema generation, and what do new projects use instead?

## The short version Django REST Framework has shipped its own OpenAPI generator for years: a `SchemaGenerator` that walks the URLconf, a per-view inspector called `AutoSchema`, a `generateschema` management command, and a `get_schema_view()` helper that serves the schema at a URL. In DRF 3.18 all of this still exists and still works, but the documentation marks it **deprecated in favour of third-party packages**, says it will be moved into a separate package and later retired, and recommends **drf-spectacular** as the replacement. The older **CoreAPI** schema support is already gone: DRF 3.17.0 dropped it. An interviewer asking "how do you document a DRF API?" in 2026 expects that picture, not a tutorial on the built-in generator. ## What the built-in generator gives you - **`generateschema`** — a management command that writes the schema offline: `./manage.py generateschema --file openapi-schema.yml`. Its `--format` option takes `openapi` (YAML, the default) or `openapi-json`; `--title`, `--description`, `--url`, `--urlconf` and `--api_version` fill the document's metadata and scope. - **`get_schema_view()`** — builds a `SchemaView` you route in `urls.py` to serve the schema dynamically. It accepts `title`, `description`, `version`, `url`, `urlconf`, `patterns`, `public`, `generator_class`, and authentication and permission classes that default to your project's defaults. - **`DEFAULT_SCHEMA_CLASS`** — the setting naming each view's inspector, `rest_framework.schemas.openapi.AutoSchema` by default. Subclassing `AutoSchema` is the built-in way to customise output. - **The document** — an OpenAPI **3.0.2** document with `openapi`, `info`, `paths` and, when serializers exist, `components.schemas`. Per-view control uses the same pieces: set `schema = None` on a view class, or decorate a function view with `@schema(None)`, to leave it out; pass `tags`, `operation_id_base` or `component_name` to `AutoSchema` to group operations, stabilise operation ids and name components; and subclass `AutoSchema` to override hooks such as `get_request_serializer()`, `get_response_serializer()` or `get_responses()`. The built-in generator needs `pyyaml` for YAML output and `uritemplate` to read path parameters; DRF's schema guide lists them, plus `inflection` for pluralised operation names. ## Why it was deprecated, in practice The built-in generator covers the happy path: one serializer per view, one success response per operation. Real APIs need more, and the DRF documentation's own recommendation reflects that: - **Responses** — it documents a single success response (`201` for `POST`, `204` for `DELETE`, `200` otherwise) with an empty description; validation, authentication and not-found errors are absent. - **Different input and output bodies** need an `AutoSchema` subclass overriding `get_request_serializer()` / `get_response_serializer()`. - **Fields it cannot map**, such as `SerializerMethodField`, fall back to type `string`. - **Security schemes** are not emitted at all. ## What teams use instead The DRF documentation names two third-party generators: | Package | Output | DRF docs' description | |---|---|---| | **drf-spectacular** | OpenAPI 3 | The recommended replacement; focuses on extensibility, customisation and client generation, with decorators and extensions for overrides and support for Swagger UI and Redoc | | **drf-yasg** | Swagger / OpenAPI 2 | Implemented without DRF's schema generation; also ships a Swagger UI viewer | Adopting drf-spectacular follows the same shape as the built-in tooling: 1. Add it to `INSTALLED_APPS`. 2. Point `DEFAULT_SCHEMA_CLASS` at `"drf_spectacular.openapi.AutoSchema"` in `REST_FRAMEWORK`. 3. Route its schema view (`SpectacularAPIView`) and, if wanted, its Swagger UI and Redoc views (`SpectacularSwaggerView`, `SpectacularRedocView`), which point at the schema view by URL name. 4. Replace per-view customisation with the package's decorators where the automatic output is wrong. For a greenfield project the choice is about OpenAPI 3 versus 2: a new API should publish OpenAPI 3, which is what the recommended package produces. ## What to say about an existing project on the built-in generator - It is not an emergency: the code is present and working in 3.18, and DRF's deprecation policy removes features only after warning releases. - Plan the move anyway, because the built-in generator will leave the core package, and every `AutoSchema` subclass you write now is migration work later. - Migrate by swapping `DEFAULT_SCHEMA_CLASS` to the new package's `AutoSchema`, re-expressing each built-in `AutoSchema` subclass as that package's decorators or extensions, and diffing the old and new documents before any consumer switches over; the new generator will usually describe more, and that difference deserves a review. - Check that nothing still depends on CoreAPI: the CoreAPI schema module and its `coreapi` integration no longer exist from 3.17.0, so any code or setting still pointing at them fails on upgrade.