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.2.2 (2026-07-25)

Bug Fixes

• openapi: Clarify WebSocket route rebinding (26360ed)

• openapi: Document preserved dependency overrides (ce4e7f5)

• openapi: Isolate flattened routes between apps (62b7161)

• openapi: Preserve overrides when flattening routers (13b8175)

• openapi: Remove project-specific changelog entry (36d8fc8)

• openapi: Remove project-specific implementation notes (e2150fc)

v0.2.1 (2026-07-20)

Bug Fixes

• Flatten lazily-mounted routers to avoid FastAPI >=0.139 memory regression (#15, 21db307)

v0.2.0 (2026-07-05)

Features

• Support Python 3.11 (#13, ab9301d)

v0.1.0 (2026-07-05)

• Initial Release

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