Framework
tfranzel/drf-spectacular avatar
tfranzel/drf-spectacular

drf-spectacular and the support floors its own metadata undercuts

Sane and flexible OpenAPI 3 schema generation for Django REST framework.

2,872 stars347 forksPythonBSD-3-Clause

At a glance

What is it?
OpenAPI 3 schema generation for Django REST framework, generated from serializers, views and docstrings, with a third-party integration list and a self-contained UI option for air-gapped installs. Its README lists Django 3.2 as the oldest supported version while the packaging metadata will install into 2.2, and it carries a Production/Stable classifier next to a policy of deliberately breaking you between releases.
Who is it for?
drf-spectacular fits a Django REST Framework service that already has serializers and a schema class set up, and it will extract more from your existing code than the generator it replaces did, at the cost of a schema you have to review on every upgrade. Four things to settle before you adopt it.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 23 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • tfranzel/drf-spectacular2,872 ★ · +9
Star history
Repository2026-10-042026-11-15
tfranzel/drf-spectacular2.9k2.9k

9 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The support matrix and the installable floors disagree

The requirements section gives three lines: Python 3.8 or later, Django from 3.2 through 6.0, and Django REST Framework from 3.12 through 3.17. The packaging metadata tells a different story to the installer. Its dependencies declare Django 2.2 or later and DRF 3.10.3 or later, and its classifiers advertise Django 2.2 alongside the versions the README lists, plus Python 3.6 and 3.7, which its own requires-python field of 3.8 or later forbids. So there are three different statements about the floor, and the one pip acts on is the lowest of them. A reader who trusts the README will believe an unsupported combination is out of scope, while an operator reading the metadata will believe the same combination is fine.

A Production/Stable classifier beside a policy of breaking you

The metadata classifies the project as Development Status 5, Production/Stable. The release management section says the opposite in so many words: the project deliberately stays below version 1.x to signal that every new version may potentially break you, it recommends pinning the version in production and inspecting a schema diff on update, and it concedes that even slight schema changes may break a toolchain because any existing bug may somehow also be used as a feature. The increment semantics follow the same honesty. A y-stream increment may contain potentially breaking changes to both the API and the schema, while a z-stream increment will never break the API and should have a low chance of breaking the schema. So the classifier describes the packaging, and the prose describes the upgrade experience.

Two extras resolve to one package, and the README names only one

The self-contained UI section exists for environments with no direct internet access, where Swagger UI and Redoc cannot be fetched from CDNs. The solution is a separate optional package, drf-spectacular-sidecar, installed by asking for the sidecar extra. Add the sidecar app to installed apps, which the comment says is required for Django collectstatic discovery, then point SWAGGER_UI_DIST, SWAGGER_UI_FAVICON_HREF and REDOC_DIST at the string SIDECAR in SPECTACULAR_SETTINGS. In the packaging metadata the optional dependencies declare an offline extra and a sidecar extra, and both name the same package. The README documents the sidecar spelling only, so an offline installer who reads the metadata will find a second, equally valid name for it.

Three edits to a Django project and no required settings

Installation is a pip install, then the package name in INSTALLED_APPS, then a schema class in the REST_FRAMEWORK dictionary pointing at drf_spectacular.openapi.AutoSchema. After that the file says the package ships with default settings that should work reasonably well out of the box, that specifying settings is not necessary, and that at least some metadata should be specified anyway. The example metadata is a title, a description, a version and SERVE_INCLUDE_SCHEMA set to False, which is what keeps the schema out of the browsable interface it would otherwise appear in. Everything beyond those three edits is optional: OpenAPI 3.1 arrives through a setting called OAS_VERSION, and the README advertises 3.0.3, 3.1 and 3.2 support.

Generation is a management command, and review is a container run

The quick tour is two commands. The first generates the schema to a file, using the spectacular management command with a colour flag and an output path. The second runs a Swagger UI container that publishes port 8080, mounts that schema file into the container and points its SWAGGER_JSON variable at it, so the schema can be looked at without wiring a view into the application. There is a validate flag for checking the output, and the alternative is serving the schema from the API itself with SpectacularAPIView, with Redoc and Swagger-UI views available as well. That makes the review loop a file plus a container, which is a workable arrangement for a pull request that changes a serializer.

Six requirement files, three test doors, and an unexplained helper directory

The tree carries more entry points than the README mentions. requirements.txt is a list of six includes, pulling base, testing, linting, optionals, packaging and docs requirements into one install. Testing can be started from runtests.py, from tox.ini or from the tests directory, and there is a MANIFEST.in for packaging. A helper directory sits at the root beside the package itself, and nothing in the visible text says what is in it. Alongside those sit CHANGELOG.rst and CONTRIBUTING.rst in reStructuredText, a readthedocs configuration, and a codecov configuration matching the coverage badge. The library's own runtime dependencies are few: uritemplate, PyYAML, jsonschema and inflection, with typing-extensions pulled in only below Python 3.10.

A fork of the generator it replaced, which lacked most of this

The project describes itself as a heavily modified fork of the DRF OpenAPI generator, and says that generator was lacking all of the features it then lists. That list is the real specification: serializers modelled as components with arbitrary nesting and recursion, an extend_schema decorator for APIViews, viewsets, function-based views and actions, polymorphic responses either manually or through another package's serializer, authentication support, type hints for SerializerMethodField, tags extraction, examples, descriptions taken from docstrings, vendor extensions in the x- namespace, operation identifiers named from the path, an optional split between input and output components, callback operations, and 3.1 through a setting. Underneath sits a list of twelve third-party packages with included support, among them Pydantic from version 2, django-filter, SimpleJWT and Knox. Two entries in that list are named as forks rather than as the original projects: one JWT package is listed together with a tested fork of it, and one auth package together with a maintained fork of the original project it replaces. Where an upstream package is abandoned, the artefact this project tests against is somebody else's branch, which is a dependency worth reading twice before it goes into a service you have to keep working.

Three releases in twenty months, every one of them below 1.0

The release record is short and unhurried. 0.28.0 was published on 2024-11-30, 0.29.0 on 2025-11-02 and 0.30.0 on 2026-07-06, so between the first and the last of those twenty months there were two releases, and each waited roughly seven or eight months for the next. The last push to master was on 2026-09-02, two months after the newest tag, which fits a project whose changes arrive as a steady drip rather than in bursts. The version numbers themselves are the release policy in shorthand: a zero major, three minors, and the prose explaining that the zero is deliberate. With 2862 stars, 337 forks and 215 open issues, the issue count is the largest of the three by a wide margin, which is what a project that extracts a schema from other people's code tends to accumulate.

Editorial conclusion

drf-spectacular fits a Django REST Framework service that already has serializers and a schema class set up, and it will extract more from your existing code than the generator it replaces did, at the cost of a schema you have to review on every upgrade. Four things to settle before you adopt it. Pin the version and diff the schema on update, because the release notes say every new version may potentially break you and that any existing bug may be used as a feature somewhere in your toolchain. Decide which extras you want, since the offline and sidecar extras both resolve to the same optional package and only one of them appears in the README. Read the floors from the packaging metadata rather than the README, because the two disagree about Django and DRF versions and the metadata is what pip acts on. And if your environment cannot reach a CDN, install the sidecar package before you rely on the bundled Swagger UI or Redoc views.

Frequently asked questions

how to install drf spectacular

Install it with pip, add drf_spectacular to INSTALLED_APPS, and set REST_FRAMEWORK DEFAULT_SCHEMA_CLASS to drf_spectacular.openapi.AutoSchema. The README says specifying SPECTACULAR_SETTINGS is not necessary because the defaults should work out of the box, but recommends adding at least some metadata.

what is drf spectacular

It generates OpenAPI 3 schemas for Django REST Framework, with three stated goals: extract as much schema information from DRF as possible, make the schema usable in real applications rather than toy examples, and produce output that works with popular client generators. It is a heavily modified fork of the DRF OpenAPI generator.

Which Python, Django and DRF versions does drf-spectacular support?

The README lists Python 3.8 and later, Django from 3.2 to 6.0, and DRF from 3.12 to 3.17. The packaging metadata is lower: it declares Django 2.2 or later and DRF 3.10.3 or later as dependencies, and its classifiers list Django 2.2 along with Python 3.6 and 3.7.

Why is drf-spectacular still below version 1.0?

The release notes say the project deliberately stays below 1.x to signal that every new version may potentially break you, and recommend pinning the version for production and inspecting a schema diff on update. A y-stream increment may break both API and schema, while a z-stream increment will not break the API.

How do I serve Swagger UI without internet access?

Install the optional sidecar package with the sidecar extra, add drf_spectacular_sidecar to INSTALLED_APPS so collectstatic can find it, then set SWAGGER_UI_DIST, SWAGGER_UI_FAVICON_HREF and REDOC_DIST to the string SIDECAR in SPECTACULAR_SETTINGS. The package exists because some environments cannot retrieve Swagger UI or Redoc from CDNs.

Official sources

  1. License: BSD-3-Clause
  2. Project website
  3. README
  4. Releases
  5. tfranzel/drf-spectacular on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tfranzel-drf-spectacular.svg)](https://hysenlabs.com/projects/tfranzel-drf-spectacular)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tfranzel-drf-spectacular.svg)](https://hysenlabs.com/projects/tfranzel-drf-spectacular)

Was this useful?