Reference: middleware¶

The machinery that discovers versions and inherits routes between them. Imported from the package root:

from fastapi_easy_versioning import (
    API_VERSION_KEY,
    VersioningMiddleware,
    rebuild_versioning,
)

VersioningMiddleware¶

fastapi_easy_versioning.VersioningMiddleware ¶

VersioningMiddleware(
    app: ASGIApp, *, rebuild_openapi: bool = True
)

Middleware that provides and manages versioned APIs.

Adds support for versioned APIs by mounting version-specific subapplications under a single FastAPI instance. On the first ASGI event it inherits versioned endpoints from older versions into newer ones and regenerates each version's OpenAPI schema. Requests themselves are routed by the mounts; use rebuild_versioning to pick up routes added at runtime.

Add it to the application that directly mounts the version sub-apps, never to the sub-apps themselves. Several instances may coexist in one application tree — each versions only the sub-apps mounted directly under its own app, so independent APIs version separately.

Only endpoints marked with versioning are inherited, and a version that declares its own endpoint on the same path shadows the inherited one — at runtime and in the OpenAPI schema alike.

Usage

from fastapi import FastAPI
from fastapi.middleware import Middleware

app = FastAPI(middleware=[Middleware(VersioningMiddleware)])
# or alternatively
app.add_middleware(VersioningMiddleware)

app.mount("/v1", FastAPI(api_version=1))
app.mount("/v2", FastAPI(api_version=2))

Parameters:

Name	Type	Description	Default
`app`	`ASGIApp`	The wrapped application, supplied by `add_middleware` or `Middleware` — do not pass it yourself.	required
`rebuild_openapi`	`bool`	Regenerate each version's OpenAPI schema after inheritance. With `False` the endpoints are still inherited and served, but inherited ones do not show up in the version's `/docs`. Defaults to `True`.	`True`

rebuild_versioning¶

fastapi_easy_versioning.rebuild_versioning ¶

rebuild_versioning(
    app: Starlette, *, rebuild_openapi: bool = True
) -> None

Build (or explicitly rebuild) versioned routes of an application.

VersioningMiddleware calls this once on its first ASGI event — the lifespan startup under a real server, the first request when the middleware sits on a mounted sub-app or in a test client. Nothing is versioned before that, and anything registered afterwards needs an explicit call:

app.mount("/v3", app_v3)
rebuild_versioning(app)

The call is idempotent, and a default (undeclared) until is re-resolved against the new latest version. An application that mounts no version sub-app is a graceful no-op.

Parameters:

Name	Type	Description	Default
`app`	`Starlette`	The application that directly mounts the version sub-apps.	required
`rebuild_openapi`	`bool`	Regenerate each version's OpenAPI schema after inheritance. Defaults to `True`.	`True`

API_VERSION_KEY¶

fastapi_easy_versioning.API_VERSION_KEY `module-attribute` ¶

API_VERSION_KEY: Final = 'api_version'

Name of the FastAPI() keyword that declares a sub-app's API version.

Unknown keywords land in FastAPI.extra, which is where the middleware reads this one from. The value must be an int (0 is valid, bool is not); a sub-app without it — or with a value of another type, which also emits a UserWarning — takes no part in versioning.