Справочник: middleware

Механика, которая объявляет версии, находит их и наследует между ними роуты. Импортируется из корня пакета:

from fastapi_easy_versioning import (
    API_VERSION_KEY,
    VersioningMiddleware,
    rebuild_versioning,
    versionize,
)

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 — each declared with versionize — 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", versionize(FastAPI(), 1))
app.mount("/v2", versionize(FastAPI(), 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

versionize

fastapi_easy_versioning.versionize

versionize(app: _AppT, version: int) -> _AppT

Declare the API version of a sub-application.

Marks app as version version for the VersioningMiddleware of the application it gets mounted under, and returns the very same object, so the call can wrap the app inline. Not to be confused with versioning: versionize declares which version an application is, versioning() marks which of its endpoints are inherited by later versions.

The declaration is read when versioning is built — on the middleware's first ASGI event. A version declared or mounted after that needs an explicit rebuild_versioning call.

Usage

app_v1 = versionize(FastAPI(), 1)
app.mount("/v1", app_v1)
app.mount("/v2", versionize(FastAPI(title="v2"), 2))

Parameters:

Name	Type	Description	Default
app	FastAPI	The version sub-application; it is modified in place.	required
version	int	The version number. Any int is valid, 0 and negative numbers included; bool is rejected.	required

Returns:

Name	Type	Description
FastAPI	_AppT	The same app object, typed as passed in.

Raises:

Type	Description
TypeError	app is not a FastAPI application, or version is not an int.
ValueError	app is already declared with a different version.

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 deprecated FastAPI() keyword that declares a sub-app's version.

Declare versions with versionize instead. On FastAPI < 0.145 unknown keywords still land in FastAPI.extra, which is where the middleware reads this one from when the app has no versionize declaration. The value must then be an int (0 is valid, bool is not); a value of another type emits a UserWarning and leaves the app out of versioning.

Warning

Deprecated since 0.4.2. FastAPI 0.145 removed **extra, so the keyword only works on FastAPI < 0.145, and declaring a version with it emits a FutureWarning. The keyword and this constant will be removed together with support for FastAPI < 0.145.

Usage

app_v1 = FastAPI(api_version=1)  # deprecated: FastAPI < 0.145 only
app_v1 = versionize(FastAPI(), 1)  # instead