drf-yasg points new projects at a different generator

The README redirects new projects

The most important section of the file is the one about what this project will not do. If you are adding schema support to a new project, it says, consider a different library that shares most of its goals while working with OpenAPI 3.0, and it names that library. The reasoning given is that 3.0 provides considerably more flexibility in the kinds of API that can be described, and then comes the sentence that settles the future: this project is unlikely to, if ever, gain OpenAPI 3.0 support. So the file is simultaneously a specification, a quickstart and a recommendation against itself for anything greenfield. That is unusual, and it is more useful than it first sounds, because the alternative library it points at is the one a new project should be using.

Support for old versions ends the day a new one ships

The support policy is stated in five sentences and every one of them is restrictive in a different way. Only the latest version is supported, and support of old versions is dropped immediately when a new version is released. You are asked not to open issues before upgrading to the version available at the time. Regression reports are accepted and will be resolved in a new release. And removed features usually go through a deprecation cycle of a few minor releases, which is the one concession. The compatibility matrix adds its own narrowness: framework, web framework and language minimums are listed, and then a sentence saying only the latest patch of each major.minor series of those three is supported. In practice this means a distribution that ships an older patch of a supported minor line is out of scope, which is a narrower promise than the minimum version numbers suggest.

Four URLs from one view object

The quickstart builds a single view from an information object carrying a title, a default version, a description, terms of service, a contact and a licence name, and then wires that one view into four routes. Two of them serve the specification itself in two formats, at a path with a format placeholder, and two of them serve interactive documentation, one for each bundled viewer. The install step is one command:

pip install --upgrade drf-yasg

There is a second command for the validation extra, which the README describes as needed only if you want the built-in validation mechanisms. The application list needs two entries, one of which is a Django static files application, and the comment beside it says why: it is required for serving the viewer's style and script files. So the viewer is bundled but not self-hosting, and the host application has to serve its assets.

The quickstart makes the schema public

The example passes the view two settings that decide who can see your API's shape: a public flag set to true and a permission class that allows anyone. The parameter reference then describes what the flag actually does, and it is not a visibility toggle: if it is false, the generated schema includes only the endpoints the current user has access to. So the two settings pull in opposite directions from what their names suggest. Set true and the schema is a complete document served to everyone; set false and it becomes a per-user document that changes shape depending on who is asking. Two further parameters exist for the view itself rather than for the schema, authentication classes and permission classes, which control who may request the schema at all.

An import that does not match the call

Two small mismatches sit inside the documented configuration surface. The quickstart imports a regular expression path helper from the framework's URL module and then writes its routes with the plain path helper instead, so the import is unused in the example as printed. And the parameter reference says the generator class should be a subclass of a generator named for OpenAPI, in a project whose entire stated output is the 2.0 flavour. Neither breaks anything, and both are the kind of detail that survives in a widely copied snippet. Read together they suggest a codebase that has moved on from one naming scheme and one example, which is normal, and a documentation site that was assembled from several eras, which is also normal.

Validation is both an extra and a base dependency

The installation section says the built-in validation mechanisms require installing an extra. The manifest lists the validator library in the base dependency list, with no marker attached. So a plain install appears to bring the validator along, while the documentation asks you to name the extra explicitly to get validation. The parameter reference adds a third piece: validators are configured by name, and only one name is currently supported. Three statements about one feature, in three files, and the reader has to guess which combination is the supported one. The practical move is to install the extra, name the single validator you are told about, and check the generated document rather than trusting the wording.

The bundled viewers are npm packages, pinned in a second manifest

A Python project with a JavaScript manifest at its root turns out to be how the two interactive viewers are supplied. Both appear as dependencies with a major version, one of them the documentation viewer and one the developer-facing viewer, and an overrides block pins a couple of transitive packages. There is no build step for them in the repository; they are version pins, and whatever gets vendored is whatever those ranges resolve to. The development side of the same manifest carries a spell checker, which for a documentation-heavy project is a real part of the toolchain, plus a couple of unrelated helpers. The figures in the README point at screenshots by an early release tag rather than at the branch, so the images a reader sees are pinned to an old version of the file.

A dummy version when the tag cannot be read

The legacy packaging script is a small lesson in defensive versioning. It tries to build using a version derived from the source control tag, and if the tool that does that is missing it does not simply fail. Locally it builds anyway, with a placeholder version built from a timestamp, and prints the traceback so the developer knows something went wrong. On a continuous integration system it re-raises instead, with a comment explaining why: they do not want to accidentally push a placeholder version to the package index. The container tells a similar story. It builds on a language version inside the supported range, installs the library from its source, then installs the requirements of the bundled example project and makes that project the default command, running its static files collection and database migrations first. Nothing in it creates an unprivileged user, and it binds port 80.

Editorial conclusion

drf-yasg fits an existing Django REST Framework service that needs documentation and client generation from OpenAPI 2.0 today, especially one where a schema view is already cached and versioned. Check four things before adopting it: whether you need OpenAPI 3.0 at all, since the project states it will not gain it and points new work at a different library, whether you accept a support policy where only the current release is supported, whether your versioning scheme is one of the two it handles, and whether you want the schema endpoint public. The quickstart wires it up as public with no permission class, which is the right default for documentation and the wrong one if your endpoints are per-user.

Frequently asked questions

Official sources

1. axnsan12/drf-yasg on GitHub
2. Issues
3. Project website
4. README
5. Releases