skip to content

OpenAPI Generation

2 roadmaps4 questions

DRF's built-in schema generation is deprecated, so teams use a third-party generator to describe request and response schemas as OpenAPI. Interviewers compare the browsable API with generated docs.

part ofDjango REST Frameworkoverview, primer and where to startread it →
on this pageshow

explore

questions

4

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

level: middleimportance: must knowfreq 55%

answer

  1. still ships, no longer recommended
  2. an older format already removed
  3. a management command and a view
  4. one third-party OpenAPI 3 package

basics

~10 s

DRF 3.18 still ships SchemaGenerator, AutoSchema, generateschema and get_schema_view, but its documentation deprecates them in favour of third-party packages and recommends drf-spectacular for OpenAPI 3. CoreAPI schema support was already removed in 3.17.0.

solid answer

~40 s

The built-in pieces — `SchemaGenerator`, the per-view `AutoSchema` set by `DEFAULT_SCHEMA_CLASS`, the `generateschema` command and `get_schema_view()` — still work in 3.18 and emit OpenAPI 3.0.2, but DRF's documentation marks them deprecated, to be moved into a separate package and retired, and recommends drf-spectacular. The legacy CoreAPI schemas are gone since 3.17.0. The built-in generator covers the happy path only: one success response per operation, one serializer per view, no security schemes. So a new project installs drf-spectacular, points `DEFAULT_SCHEMA_CLASS` at its `AutoSchema`, routes its schema, Swagger UI and Redoc views, and uses its decorators where the automatic output is wrong. An existing project on the built-in generator is fine for now but should plan the move.

code

bash · 2 lines
bash
./manage.py generateschema --file openapi-schema.yml
./manage.py generateschema --format openapi-json --api_version 2.1.0 --file openapi-schema.json

go deeper

for a junior

Remember that DRF's own schema generator is deprecated and that the DRF docs recommend drf-spectacular for OpenAPI documentation.

for a middle

Explain the built-in pieces, generateschema, get_schema_view and DEFAULT_SCHEMA_CLASS, what they emit, and how swapping the schema class adopts a third-party generator.

for a senior

Show you know why the built-in output falls short (single success response, no security schemes, weak field typing) and plan the migration before the code leaves core.

for a principal

Weigh the migration cost of existing AutoSchema subclasses against the deprecation timeline, and pick the OpenAPI version your consumers' tooling needs.

## 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.

  • Does deprecated mean the built-in generator stops working on upgrade to 3.18?
    No. In 3.18 `SchemaGenerator`, `AutoSchema`, `generateschema` and `get_schema_view()` are present and functional; the deprecation is a documented direction: the code will move to a separate package and then be retired. DRF's deprecation policy removes features only after releases that warn, which is exactly what happened to CoreAPI before 3.17.0 dropped it.
  • When would you still choose drf-yasg?
    Mainly when a consumer's tooling requires Swagger 2.0, since drf-yasg generates Swagger / OpenAPI 2 while the recommended drf-spectacular generates OpenAPI 3. For a new API with no such constraint, publish OpenAPI 3.

saying these in an interview costs you the question

  • Recommending DRF's built-in generator for a new project in 2026
  • Believing DRF 3.18 already removed the built-in OpenAPI generator
  • Still configuring CoreAPI schemas on DRF 3.17 or later
  • Assuming the built-in schema documents error responses automatically
  • Treating drf-yasg's Swagger 2.0 output as equivalent to OpenAPI 3
open as a page

In Django REST Framework, how does the browsable API differ from generated OpenAPI documentation, and why is it no substitute?

level: juniorimportance: should knowfreq 44%

basics

~20 s

The browsable API is an HTML renderer that shows one endpoint at a time, live, to a person in a browser acting as the current user. Generated OpenAPI documentation is a machine-readable description of every operation that partners and tools can use without your server.

open as a page

In Django REST Framework, why does a generated OpenAPI schema often misdescribe request and response bodies, and how do you correct it?

level: middleimportance: should knowfreq 38%

basics

~20 s

A DRF generator infers bodies from view.get_serializer(): one serializer for request and response, one success status, fallback types for unmappable fields. Correct it by declaring separate request and response serializers, error responses and explicit types, via AutoSchema overrides or a third-party generator's decorators.

open as a page

Your team publishes a Django REST Framework API's OpenAPI schema to external partners; how do you keep that schema honest as the code changes?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Publish a generated, versioned schema file rather than a live, permission-filtered schema view; regenerate it in CI and fail on any diff or generator warning; exclude internal views, validate the document, and add error responses and auth the generator cannot infer.

open as a page