Running multiple API versions side by side usually means duplicating routers, hand-rolling prefixes, or branching on request paths. RouterVersioner does it declaratively instead: annotate each route with the version it belongs to, and it generates the URL prefixes, the per-version OpenAPI schema, and the docs, without moving anything else in your app.
Documentation: https://fastapi-router-versioning.matblack81.com/
Features
- SemVer and CalVer: version routes with
(major, minor)tuples, or with arbitrary sortable strings - Per-version docs: isolated Swagger UI, ReDoc, and
openapi.jsonfor every active version - Declarative lifecycle: mark a route's introduction, deprecation, and removal with one decorator
- Deprecation headers: opt-in
Deprecation,SunsetandLinkresponse headers on routes in their deprecation window - Latest alias: expose the newest version under a fixed
/latestprefix clients can pin to - Self-hosted docs assets: point Swagger UI and ReDoc at your own JS/CSS for air-gapped deployments
- Reverse proxy and sub-app aware: doc URLs pick up the ASGI
root_pathat request time - Route composition support: works across nested routers, WebSockets,
Depends, and OpenAPI Callbacks
Requirements
- Python ≥ 3.10
- FastAPI ≥ 0.120.0, except
0.137.0and0.137.1
Why two FastAPI versions are excluded
0.137.0and0.137.1shipped a routing internals rewrite beforeiter_route_contexts()landed in0.137.2, which this package relies on. Supporting that narrow gap would have meant a third compatibility code path instead of the two the package actually needs.
Installation
pip install fastapi-router-versioning
# or
uv add fastapi-router-versioning
Quick start
RouterVersioner is not a request-time dependency; there's no Depends() involved. It's a
one-time setup step: you build it, then call .versionize() once, and it reads the routers
you gave it and mounts one copy per version. Attach @api_version to every route before
calling .versionize(), since that call is what reads the router and wires everything up;
routes added to the router afterward are never picked up.
from fastapi import APIRouter, FastAPI
from fastapi_router_versioning import (
RouterVersioner, VersionFormat, api_version,
)
app = FastAPI()
router = APIRouter()
@router.get("/items")
@api_version((1, 0))
def get_items_v1():
return {"version": "1.0", "items": ["a", "b"]}
@router.get("/items")
@api_version((2, 0))
def get_items_v2():
return {"version": "2.0", "items": ["a", "b", "c"]}
RouterVersioner(
app=app, routers=router,
version_format=VersionFormat.SEMVER
).versionize()
CalVer, the route lifecycle, the parameter reference and the advanced options are in the documentation.
Release Notes
License
Metadata
Release files for fastapi-router-versioning 1.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fastapi_router_versioning-1.2.2.tar.gz | 1.1 MB | Without provenance | Details for fastapi_router_versioning-1.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fastapi_router_versioning-1.2.2-py3-none-any.whl | Python 3 | none | any | Details for fastapi_router_versioning-1.2.2-py3-none-any.whl |
Total release size: 1.1 MB
Release files / fastapi_router_versioning-1.2.2.tar.gz
| Download URL | fastapi_router_versioning-1.2.2.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc51307ddc0baff85f2090954fa0ed32e43cdec81624ac4517a7fd438e4b2d65
|
|
BLAKE2b-256 checksum How to use checksums |
c437b70a25b5a87c16cd0de8eb3f53949e886988f00ee07442c7a3077ca559c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.18 {"installer":{"name":"uv","version":"0.11.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / fastapi_router_versioning-1.2.2-py3-none-any.whl
| Download URL | fastapi_router_versioning-1.2.2-py3-none-any.whl |
|---|---|
| Size | 25.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a0e413ccf2b2c6ea3682903434b42bf38ce1a612c76a6129b5e6270a5f21f565
|
|
BLAKE2b-256 checksum How to use checksums |
4b5a7e0b58efa72c39986b33c34c7c322cdae4674273a8dba855b71f6d3e14a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.18 {"installer":{"name":"uv","version":"0.11.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for fastapi-router-versioning 1.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.