Flask-RESTX: Swagger documentation generated from the same decorators that build your routes

A fork of Flask-RESTPlus with a long history behind it

The repository describes itself in one line as a fork of Flask-RESTPlus, the extension that Noirbizarre wrote and then stopped maintaining. That origin story is the main reason to care: Flask-RESTX inherited a mature, widely deployed decorator based API and has spent its life keeping it working as Flask itself moved underneath it. The README says it is an extension for Flask that adds support for quickly building REST APIs, encourages best practices with minimal setup, and provides a coherent collection of decorators and tools to describe your API and expose documentation properly using Swagger.

The maintenance note in the README is unusually honest about who is doing the work. It says the project is brought to you by @python-restx, that since early 2019 @SteadBytes, @a-luna, @j5awry and @ziirish volunteered to keep it running for a long time, and that since the beginning of 2023 the project has been maintained by @peter-doggart with help from @ziirish. That is effectively a single maintainer with a long tail of intermittent help, which is the single most important thing to know before depending on it. The star count and fork count are both around the two thousand mark, and the open issue count is over three hundred, a ratio that says adoption has outpaced maintenance capacity for a while.

A compatibility table for Flask and Werkzeug versions

Flask-RESTX requires Python 3.10 or newer, which rules out a lot of older enterprise environments immediately. The README then dedicates a table to Flask compatibility, because Flask and Werkzeug moved to version 2.0 in March 2020 and that caused a breaking change. The table walks through the versions: at or below 0.3.0 of Flask-RESTX you are on Flask below 2.0.0 and Flask-RESTX is unpinned, so the README tells you to pin your own projects. Version 0.4.0 stays on Flask below 2.0.0. From 1.3.0 onward the requirement is Flask 2.0.0 or newer, which the table annotates as Flask 3.0.0 support, again unpinned, with import statements wrapped for compatibility.

The last row is the interesting one, and it is a candid admission rather than a promise: the trunk branch in GitHub tracks Flask 2.0.0 or newer, is unpinned, and will address issues faster than releases. In other words, if you hit a bug, the trunk branch is where the fix already is. That is a useful escape hatch and also a signal about how much slower the release train has become. The current release is 1.3.2 from September 2025, and the 1.3.2 notes are almost entirely compatibility work: replacing pytz with zoneinfo, moving from `jsonschema.RefResolver` to the newer referencing library, adjusting testing for Flask 3.1.0 changes, and a fix to a unit test. Two years of accumulated Flask compatibility patches, and most of them land in a single maintainer's hands.

Documenting the API with the same decorators that route it

The quick start is a TodoMVC API, and it is worth reading closely because it shows the whole mental model in one file. You create an `Api` bound to the app with a version and title, define a `model` describing your response shape with typed fields, create a namespace for grouping, and then attach documentation decorators to resource classes:

from flask import Flask
from flask_restx import Api, Resource, fields

app = Flask(__name__)
api = Api(app, version='1.0', title='TodoMVC API',
    description='A simple TodoMVC API',
)

The model definition is where response validation comes from, and it is the part that saves the most typing later:

todo = api.model('Todo', {
    'id': fields.Integer(readonly=True, description='The task unique identifier'),
    'task': fields.String(required=True, description='The task details')
})

Because the model is named, you can pass it to `marshal_with` and `marshal_list_with` on your methods, and the same declaration that documents the response also filters and serialises it. `expect` handles request bodies, `doc` gives an operation an identifier that shows up in the generated docs, `param` documents a single parameter, and `response` declares an error code and its message. The README states the model plainly: you only import the api instance to route and document your endpoints. That is accurate, and it is the trade at the heart of the library. Documentation is not a separate artefact that can drift out of sync because it is derived from the same declarations, but your route code is now densely decorated with metadata, and there is no supported path for describing an endpoint that does not fit the decorator model.

Licence, packaging and the Swagger UI dependency

Two details in the packaging are worth flagging. The first is the licence, which is reported inconsistently. GitHub reports NOASSERTION for this repository, meaning it could not classify the licence from what it could parse, while the `package.json` in the root declares `"license": "BSD-3-Clause"` and a `LICENSE` file exists at the top level of the tree. The BSD-3-Clause declaration is the most specific statement available, but given the GitHub report, open the `LICENSE` file and confirm for yourself rather than relying on a badge.

The second is that this is an unusual kind of package, because there is a `package.json` in a Python project. It exists to pull the Swagger UI assets, declaring dependencies on `swagger-ui-dist` at a 4.x version and `typeface-droid-sans`. That is how the interactive documentation gets served without vendoring megabytes of JavaScript into the repository, and it also means an npm toolchain sits next to the Python one. Note the version mismatch: `package.json` says `1.3.1` while the newest release tag is `1.3.2`.

The rest of the tree reflects a mature Python project with the usual trimmings: `tox.ini` for test environments, `coverage.rc`, a `requirements/` directory with per-target `.pip` files that `setup.py` parses and transforms into setuptools requirements, `tasks.py` for invoke tasks, `doc/` and `examples/` directories, and a `CHANGELOG.rst`. The `setup.py` also contains a chunk of reStructuredText munging that rewrites Sphinx cross references, `:doc:` links, `:issue:` and `:pr:` references, and strips badges and `code-block` directives when uploading the long description to PyPI, since PyPI's renderer does not understand those directives.

Editorial conclusion

Flask-RESTX is a reasonable pick when the team already speaks Flask and wants browsable API documentation without maintaining a separate OpenAPI file by hand, because the decorators that define your routes are the same ones that produce the spec. Namespaces give you a natural way to group endpoints, and field marshalling gives you response validation almost for free. The tradeoffs are real: you are inside a single maintainer's care now that the project has been run by @peter-doggart with help from @ziirish since early 2023, the open issue count sits far higher than the release cadence suggests, and the licence is reported inconsistently, with BSD-3-Clause in the package manifest while GitHub itself detects nothing. For a greenfield API in 2026, FastAPI is the more obvious default; for an existing Flask codebase that needs better docs without a rewrite, this is the smaller change.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. python-restx/flask-restx on GitHub
4. README
5. Releases