fastapi-router-variants 0.1.0

Path variants, API versioning and per-version OpenAPI documentation for FastAPI routers

fastapi-router-variants

Declare a route once and get path variants, API versioning and per-version OpenAPI documentation for FastAPI — for free.

fastapi-router-variants wraps APIRouter with a RouterWrapper that expands a single route declaration into every variant it should serve — multiple paths, multiple version prefixes (/v1/..., /v2/...), multiple mount prefixes, with deprecation handled automatically — then builds a separate OpenAPI schema per version and mounts Swagger UI / ReDoc / openapi.json for each of them.

Install

pip install fastapi-router-variants
# or
uv add fastapi-router-variants

Usage

from fastapi import FastAPI

from fastapi_router_variants import RouterDefaults, RouterWrapper


class ApiDefaults(RouterDefaults):
    prefix = "/api"           # mount every route under /api
    version = True            # force versioning on every route
    version_range = (1, 3)    # generate v1, v2, v3
    version_default = 3       # the version served on unversioned doc URLs


RouterWrapper.defaults = ApiDefaults()

router = RouterWrapper()


@router.get("/users/{user_id}")
def get_user(user_id: int) -> dict[str, int]:
    return {"id": user_id}


app = FastAPI()
app.include_router(router.base)

The single get declaration above registers GET /api/v1/users/{user_id}, GET /api/v2/users/{user_id} and GET /api/v3/users/{user_id}.

Path variants and flavors, versioning helpers, routing specs, per-version OpenAPI documents, custom categories and HTTP-error auto-documentation are all covered in the documentation.

Documentation

Full documentation is available at toilal.github.io/fastapi-router-variants. A preview of the in-progress develop branch is published at toilal.github.io/fastapi-router-variants/dev.

Requirements

• Python ≥ 3.12
• FastAPI ≥ 0.115

License

MIT © Rémi Alvergnat

CHANGELOG

v0.1.0 (2026-07-05)

• Initial Release

Changelog entries are generated automatically by python-semantic-release from Conventional Commits on release.