fastapi-router-versioning 0.1.0__py3-none-any.whl

fastapi_router_versioning/__init__.py

@@ -0,0 +1,5 @@
+from .versioner import RouterVersioner, VersionFormat, VersionT, api_version
+
+__version__ = "0.1.0"
+
+__all__ = ["RouterVersioner", "api_version", "VersionFormat", "VersionT"]

fastapi_router_versioning/versioner.py

@@ -0,0 +1,564 @@
+import inspect
+
+from collections import defaultdict
+from collections.abc import Callable, Iterator
+from enum import Enum
+from typing import Any, TypeAlias, TypeVar
+
+import fastapi.openapi.utils
+import fastapi.routing
+
+from fastapi import APIRouter, FastAPI
+from fastapi.openapi.docs import (
+    get_redoc_html,
+    get_swagger_ui_html,
+    get_swagger_ui_oauth2_redirect_html,
+)
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.routing import APIRoute, APIWebSocketRoute
+from starlette.requests import Request
+
+# iter_route_contexts was introduced in FastAPI 0.137.2. On older versions the
+# attribute does not exist and getattr returns None, activating the fallback path.
+_route_contexts_fn: Callable[..., Any] | None = getattr(fastapi.routing, "iter_route_contexts", None)
+
+
+def _iter_routes_flat(routes: list[Any]) -> Iterator[Any]:
+    """
+    Flattens the route tree using iter_route_contexts (FastAPI >= 0.137.2),
+    or yields the original flat list for older versions.
+    """
+    if _route_contexts_fn is None:
+        yield from routes
+        return
+
+    for route_ctx in _route_contexts_fn(routes):
+        original = route_ctx.original_route
+        if isinstance(original, APIRoute):
+            # RouteContext merges path/tags/deps via __getattr__; use the context directly.
+            yield route_ctx
+        else:
+            yield original
+
+
+def _unwrap_route(route: Any) -> Any:
+    # RouteContext (FastAPI >= 0.137.2) wraps the original route.
+    # Attributes like response_model, status_code, operation_id live on the original.
+    return getattr(route, "original_route", route)
+
+
+CallableT = TypeVar("CallableT", bound=Callable[..., Any])
+
+VersionT: TypeAlias = tuple[int, int] | str
+
+_ATTR_API_VERSION = "_api_version"
+_ATTR_DEPRECATE_IN = "_deprecate_in_version"
+_ATTR_REMOVE_IN = "_remove_in_version"
+
+
+class VersionFormat(str, Enum):
+    """
+    Defines the allowed versioning strategy for the RouterVersioner.
+    """
+
+    SEMVER = "semver"  # Accepts tuple[int, int] (e.g., (1, 0))
+    CALVER = "calver"  # Accepts str (e.g., "2025-01-01", "v1")
+
+
+def _validate_api_version_arg(value: Any, param_name: str) -> None:
+    if not isinstance(value, (tuple, str)):
+        raise TypeError(
+            f"api_version: '{param_name}' must be a tuple[int, int] (SemVer) or str (CalVer), "
+            f"got {type(value).__name__!r} instead. "
+            "Example: @api_version((1, 0)) or @api_version('2025-01-01')."
+        )
+
+
+def api_version(
+    version: VersionT,
+    deprecate_in: VersionT | None = None,
+    remove_in: VersionT | None = None,
+) -> Callable[[CallableT], CallableT]:
+    """
+    Decorator to annotate API routes with their specific version.
+
+    Accepts both Semantic Versioning (e.g., tuple (1, 0)) and Calendar Versioning
+    or strings (e.g., "2025-01-01", "v1").
+    Metadata is injected directly into the wrapper function, allowing the
+    RouterVersioner to organize the routes dynamically.
+    """
+    _validate_api_version_arg(version, "version")
+    if deprecate_in is not None:
+        _validate_api_version_arg(deprecate_in, "deprecate_in")
+    if remove_in is not None:
+        _validate_api_version_arg(remove_in, "remove_in")
+
+    def decorator(func: CallableT) -> CallableT:
+        setattr(func, _ATTR_API_VERSION, version)  # noqa: B010
+
+        if deprecate_in is not None:
+            setattr(func, _ATTR_DEPRECATE_IN, deprecate_in)  # noqa: B010
+
+        if remove_in is not None:
+            setattr(func, _ATTR_REMOVE_IN, remove_in)  # noqa: B010
+
+        return func
+
+    return decorator
+
+
+class RouterVersioner:
+    def __init__(
+        self,
+        app: FastAPI,
+        routers: list[APIRouter] | APIRouter,
+        version_format: VersionFormat = VersionFormat.SEMVER,
+        prefix_format: str | None = None,
+        semantic_version_format: str | None = None,
+        default_version: VersionT | None = None,
+        latest_prefix: str | None = None,
+        include_version_docs: bool = True,
+        include_version_openapi_route: bool = True,
+        include_versions_route: bool = False,
+        sort_routes: bool = False,
+        callback: Callable[[APIRouter, VersionT, str], None] | None = None,
+        webhook_routers: list[APIRouter] | APIRouter | None = None,
+        openapi_hook: Callable[[dict[str, Any], VersionT], dict[str, Any]] | None = None,
+        swagger_js_url: str | None = None,
+        swagger_css_url: str | None = None,
+        swagger_favicon_url: str | None = None,
+        redoc_js_url: str | None = None,
+        redoc_favicon_url: str | None = None,
+        redoc_with_google_fonts: bool = True,
+    ):
+        """
+        Versionize your FastAPI application in-place, organizing routes based on their API version.
+
+        :param app: The main FastAPI application instance.
+        :param routers: A single APIRouter or a list of APIRouters containing the routes to version.
+        :param version_format: Enforces the versioning strategy (SEMVER or CALVER).
+            For CALVER, version strings must be lexicographically sortable in the intended
+            order (e.g. ISO dates "2025-01-01", zero-padded numbers "v01", "v02").
+            Strings like "v1", "v10", "v2" will NOT sort correctly and cause routes to
+            appear in the wrong versions.
+        :param prefix_format: Format used to build the route prefix.
+        :param semantic_version_format: Format used to build the version in Swagger/ReDoc.
+        :param default_version: Default version used if a route is not explicitly decorated.
+        :param latest_prefix: If specified, creates an alias prefix for the latest active version.
+        :param include_version_docs: If True, creates isolated Swagger/ReDoc pages for each version.
+        :param include_version_openapi_route: If True, creates an independent openapi.json route for each version.
+        :param include_versions_route: If True, adds a 'GET /versions' endpoint returning info on all active API versions.
+        :param sort_routes: If True, sorts all routes alphabetically by path.
+        :param callback: Optional hook invoked every time a versioned APIRouter is created.
+        :param webhook_routers: A single APIRouter or a list of APIRouters containing webhook definitions
+            annotated with @api_version. When provided, each version's OpenAPI schema shows only the
+            webhooks active in that version (using the same introduce/remove lifecycle as regular routes).
+            When None, every version inherits app.webhooks unchanged.
+        :param openapi_hook: Optional hook applied to the generated OpenAPI schema for each version.
+            Receives the schema dict and the current version; must return the (modified) schema dict.
+            Use this to add custom extensions, logos, or version-specific metadata that would
+            otherwise be bypassed by the per-version schema generation.
+        :param swagger_js_url: Custom URL for the Swagger UI JS bundle. Defaults to FastAPI's CDN URL.
+        :param swagger_css_url: Custom URL for the Swagger UI CSS. Defaults to FastAPI's CDN URL.
+        :param swagger_favicon_url: Custom URL for the Swagger UI favicon. Defaults to FastAPI's favicon.
+        :param redoc_js_url: Custom URL for the ReDoc JS bundle. Defaults to FastAPI's CDN URL.
+        :param redoc_favicon_url: Custom URL for the ReDoc favicon. Defaults to FastAPI's favicon.
+        :param redoc_with_google_fonts: If False, ReDoc will not load Google Fonts. Defaults to True.
+        """
+        self._app = app
+        self._routers = [routers] if isinstance(routers, APIRouter) else routers
+        self._version_format = version_format
+
+        if prefix_format is None:
+            self._prefix_format = "/v{major}_{minor}" if version_format == VersionFormat.SEMVER else "/{version}"
+        else:
+            self._prefix_format = prefix_format
+
+        if semantic_version_format is None:
+            self._semantic_version_format = "{major}.{minor}" if version_format == VersionFormat.SEMVER else "{version}"
+        else:
+            self._semantic_version_format = semantic_version_format
+
+        self._latest_prefix = latest_prefix
+        self._include_version_docs = include_version_docs
+        self._include_version_openapi_route = include_version_openapi_route
+        self._include_versions_route = include_versions_route
+        self._sort_routes = sort_routes
+        self._callback = callback
+        self._webhook_routers: list[APIRouter] | None = (
+            [webhook_routers] if isinstance(webhook_routers, APIRouter) else webhook_routers
+        )
+        self._openapi_hook = openapi_hook
+        self._swagger_js_url = swagger_js_url
+        self._swagger_css_url = swagger_css_url
+        self._swagger_favicon_url = swagger_favicon_url
+        self._redoc_js_url = redoc_js_url
+        self._redoc_favicon_url = redoc_favicon_url
+        self._redoc_with_google_fonts = redoc_with_google_fonts
+
+        if default_version is None:
+            self._default_version: VersionT = (1, 0) if version_format == VersionFormat.SEMVER else "1"
+        else:
+            self._validate_version_type(default_version, "default_version fallback")
+            self._default_version = default_version
+
+        self._docs_url = getattr(app, "docs_url", "/docs")
+        self._redoc_url = getattr(app, "redoc_url", "/redoc")
+
+    def _validate_version_type(self, version: Any, route_path: str) -> None:
+        if self._version_format == VersionFormat.SEMVER:
+            if not isinstance(version, tuple) or len(version) != 2 or not all(isinstance(i, int) for i in version):
+                error_msg = f"RouterVersioner expects SEMVER, but found an invalid version '{version}' on {route_path}. Use a tuple of exactly two integers: (major, minor). e.g., (1, 0)."
+                raise ValueError(error_msg)
+        elif self._version_format == VersionFormat.CALVER:
+            if not isinstance(version, str):
+                error_msg = f"RouterVersioner expects CALVER, but found a non-string version '{version}' on {route_path}. Use a string like '2025-01-01'."
+                raise ValueError(error_msg)
+
+    @staticmethod
+    def _format_string(format_str: str, version: VersionT) -> str:
+        if isinstance(version, tuple):
+            return format_str.format(major=version[0], minor=version[1], version=f"{version[0]}_{version[1]}")
+        return format_str.format(version=version, major=version, minor=version)
+
+    def _extract_version_attribute(self, endpoint: Any, attribute: str, route_path: str) -> VersionT | None:
+        val = getattr(endpoint, attribute, None)
+        if isinstance(val, (tuple, str)):
+            self._validate_version_type(val, route_path)
+            return val
+        return None
+
+    def versionize(self) -> list[VersionT]:
+        latest_version: VersionT | None = None
+        latest_routes: dict[tuple[str, str], Any] = {}
+        latest_webhooks: list[Any] = []
+
+        routes_by_version = self._get_routes_by_version()
+        versions = list(routes_by_version.keys())
+        webhooks_by_version = self._get_webhooks_by_version()
+
+        for version, routes_by_key in routes_by_version.items():
+            version_prefix = self._format_string(self._prefix_format, version)
+            active_webhooks = self._resolve_webhooks_for_version(version, webhooks_by_version)
+
+            version_router = self._build_version_router(
+                version=version, version_prefix=version_prefix, routes_by_key=routes_by_key, webhooks=active_webhooks
+            )
+
+            if self._callback:
+                self._callback(version_router, version, version_prefix)
+
+            self._app.include_router(router=version_router)
+
+            latest_version = version
+            latest_routes = routes_by_key
+            latest_webhooks = active_webhooks
+
+        if self._latest_prefix is not None and latest_version is not None:
+            latest_router = self._build_version_router(
+                version=latest_version,
+                version_prefix=self._latest_prefix,
+                routes_by_key=latest_routes,
+                webhooks=latest_webhooks,
+            )
+            if self._callback:
+                self._callback(latest_router, latest_version, self._latest_prefix)
+            self._app.include_router(router=latest_router)
+
+        if self._include_versions_route:
+            self._add_versions_route(versions=versions)
+
+        return versions
+
+    def _build_version_router(
+        self,
+        version: VersionT,
+        version_prefix: str,
+        routes_by_key: dict[tuple[str, str], Any],
+        webhooks: list[Any],
+    ) -> APIRouter:
+        router = APIRouter(prefix=version_prefix, responses=self._app.router.responses)
+
+        if self._sort_routes:
+            routes_by_key = dict(sorted(routes_by_key.items()))
+
+        for route in routes_by_key.values():
+            self._add_route_to_router(route=route, router=router, version=version)
+
+        self._add_version_docs(router=router, version=version, version_prefix=version_prefix, webhooks=webhooks)
+
+        return router
+
+    def _get_routes_by_version(self) -> dict[VersionT, dict[tuple[str, str], Any]]:
+        all_routes: list[Any] = []
+        for router in self._routers:
+            all_routes.extend(_iter_routes_flat(router.routes))
+
+        routes_introduced: dict[VersionT, list[Any]] = defaultdict(list)
+        for route in all_routes:
+            start_version = self._extract_version_attribute(route.endpoint, _ATTR_API_VERSION, route.path)
+            if start_version is None:
+                start_version = self._default_version
+            routes_introduced[start_version].append(route)
+
+        routes_removed: dict[VersionT, list[Any]] = defaultdict(list)
+        for route in all_routes:
+            end_version = self._extract_version_attribute(route.endpoint, _ATTR_REMOVE_IN, route.path)
+            if end_version is not None:
+                routes_removed[end_version].append(route)
+
+        all_version_keys = set(routes_introduced.keys()) | set(routes_removed.keys())
+        versions = sorted(all_version_keys)
+        routes_by_version: dict[VersionT, dict[tuple[str, str], Any]] = {}
+        active_routes: dict[tuple[str, str], Any] = {}
+
+        for version in versions:
+            for route in routes_introduced[version]:
+                active_routes.update(self._get_route_keys(route=route))
+
+            for route in routes_removed.get(version, []):
+                for route_key in self._get_route_keys(route=route):
+                    active_routes.pop(route_key, None)
+
+            routes_by_version[version] = dict(active_routes)
+
+        return routes_by_version
+
+    def _get_webhooks_by_version(self) -> dict[VersionT, list[Any]]:
+        if not self._webhook_routers:
+            return {}
+
+        all_webhooks: list[Any] = []
+        for router in self._webhook_routers:
+            all_webhooks.extend(_iter_routes_flat(router.routes))
+
+        webhooks_introduced: dict[VersionT, list[Any]] = defaultdict(list)
+        for route in all_webhooks:
+            v = self._extract_version_attribute(route.endpoint, _ATTR_API_VERSION, route.path)
+            webhooks_introduced[v if v is not None else self._default_version].append(route)
+
+        webhooks_removed: dict[VersionT, list[Any]] = defaultdict(list)
+        for route in all_webhooks:
+            v = self._extract_version_attribute(route.endpoint, _ATTR_REMOVE_IN, route.path)
+            if v is not None:
+                webhooks_removed[v].append(route)
+
+        combined_keys = set(webhooks_introduced.keys()) | set(webhooks_removed.keys())
+        result: dict[VersionT, list[Any]] = {}
+        active: dict[tuple[str, str], Any] = {}
+
+        for version in sorted(combined_keys):
+            for route in webhooks_introduced[version]:
+                active.update(self._get_route_keys(route=route))
+            for route in webhooks_removed.get(version, []):
+                for key in self._get_route_keys(route=route):
+                    active.pop(key, None)
+            result[version] = list(active.values())
+
+        return result
+
+    def _resolve_webhooks_for_version(
+        self, version: VersionT, webhooks_by_version: dict[VersionT, list[Any]]
+    ) -> list[Any]:
+        if not webhooks_by_version:
+            # webhook_routers not provided: fall back to global app.webhooks
+            return list(self._app.webhooks.routes)
+        candidates: list[VersionT] = []
+        if isinstance(version, tuple):
+            candidates = [v for v in webhooks_by_version if isinstance(v, tuple) and v <= version]
+        else:
+            candidates = [v for v in webhooks_by_version if isinstance(v, str) and v <= version]
+        if not candidates:
+            return []
+        return webhooks_by_version[max(candidates)]
+
+    @classmethod
+    def _get_route_keys(cls, route: Any) -> dict[tuple[str, str], Any]:
+        path = route.path
+        routes_by_key: dict[tuple[str, str], Any] = {}
+        route_type = _unwrap_route(route)
+
+        if isinstance(route_type, APIRoute):
+            for method in route.methods:
+                routes_by_key[(path, method)] = route
+        elif isinstance(route_type, APIWebSocketRoute):
+            routes_by_key[(path, "")] = route
+
+        return routes_by_key
+
+    def _add_version_docs(self, router: APIRouter, version: VersionT, version_prefix: str, webhooks: list[Any]) -> None:
+        doc_version_str = self._format_string(self._semantic_version_format, version)
+        title = f"{self._app.title} - v{doc_version_str}"
+        versioned_tags = self._collect_versioned_tags(router)
+        openapi_url = self._app.openapi_url
+
+        if self._include_version_openapi_route and openapi_url is not None:
+            self._add_openapi_route(router, title, doc_version_str, versioned_tags, openapi_url, version, webhooks)
+
+        if self._include_version_docs and self._docs_url is not None and openapi_url is not None:
+            self._add_swagger_ui_routes(router, title, version_prefix, self._docs_url, openapi_url)
+
+        if self._include_version_docs and self._redoc_url is not None and openapi_url is not None:
+            self._add_redoc_route(router, title, version_prefix, self._redoc_url, openapi_url)
+
+    def _collect_versioned_tags(self, router: APIRouter) -> list[dict[str, Any]]:
+        if self._app.openapi_tags is None:
+            return []
+        tags: set[str | Enum] = set()
+        for route in router.routes:
+            if isinstance(route, APIRoute) and isinstance(route.tags, list):
+                tags.update(route.tags)
+        if not tags:
+            return []
+        return [tag for tag in self._app.openapi_tags if tag["name"] in tags]
+
+    def _add_openapi_route(
+        self,
+        router: APIRouter,
+        title: str,
+        doc_version_str: str,
+        versioned_tags: list[dict[str, Any]],
+        openapi_url: str,
+        version: VersionT,
+        webhooks: list[Any],
+    ) -> None:
+        @router.get(openapi_url, include_in_schema=False)
+        async def get_openapi(req: Request) -> Any:
+            schema = fastapi.openapi.utils.get_openapi(
+                title=title,
+                version=doc_version_str,
+                openapi_version=self._app.openapi_version,
+                summary=self._app.summary,
+                description=self._app.description,
+                routes=router.routes,
+                webhooks=webhooks,
+                tags=versioned_tags,
+                servers=self._app.servers,
+                terms_of_service=self._app.terms_of_service,
+                contact=self._app.contact,
+                license_info=self._app.license_info,
+                separate_input_output_schemas=self._app.separate_input_output_schemas,
+                external_docs=self._app.openapi_external_docs,
+            )
+
+            root_path = req.scope.get("root_path", "").rstrip("/")
+            if root_path and getattr(self._app, "root_path_in_servers", True):
+                server_urls = {s.get("url") for s in schema.get("servers", [])}
+                if root_path not in server_urls:
+                    schema = dict(schema)
+                    schema["servers"] = [{"url": root_path}] + schema.get("servers", [])
+
+            if self._openapi_hook is not None:
+                schema = self._openapi_hook(schema, version)
+
+            return schema
+
+    def _add_swagger_ui_routes(
+        self, router: APIRouter, title: str, version_prefix: str, docs_url: str, openapi_url: str
+    ) -> None:
+        swagger_asset_kwargs: dict[str, Any] = {}
+        if self._swagger_js_url is not None:
+            swagger_asset_kwargs["swagger_js_url"] = self._swagger_js_url
+        if self._swagger_css_url is not None:
+            swagger_asset_kwargs["swagger_css_url"] = self._swagger_css_url
+        if self._swagger_favicon_url is not None:
+            swagger_asset_kwargs["swagger_favicon_url"] = self._swagger_favicon_url
+
+        # root_path is resolved at request time (mirrors FastAPI's own /docs handler).
+        @router.get(docs_url, include_in_schema=False)
+        async def get_docs(request: Request) -> HTMLResponse:
+            root_path = request.scope.get("root_path", "").rstrip("/")
+            versioned_openapi_url = f"{root_path}{version_prefix}{openapi_url}"
+            oauth2_redirect_url = (
+                f"{root_path}{version_prefix}{self._app.swagger_ui_oauth2_redirect_url}"
+                if self._app.swagger_ui_oauth2_redirect_url
+                else None
+            )
+            return get_swagger_ui_html(
+                openapi_url=versioned_openapi_url,
+                title=title,
+                oauth2_redirect_url=oauth2_redirect_url,
+                init_oauth=self._app.swagger_ui_init_oauth,
+                swagger_ui_parameters=self._app.swagger_ui_parameters,
+                **swagger_asset_kwargs,
+            )
+
+        if self._app.swagger_ui_oauth2_redirect_url:
+
+            @router.get(self._app.swagger_ui_oauth2_redirect_url, include_in_schema=False)
+            async def get_oauth2_redirect(_request: Request) -> HTMLResponse:
+                return get_swagger_ui_oauth2_redirect_html()
+
+    def _add_redoc_route(
+        self, router: APIRouter, title: str, version_prefix: str, redoc_url: str, openapi_url: str
+    ) -> None:
+        redoc_asset_kwargs: dict[str, Any] = {"with_google_fonts": self._redoc_with_google_fonts}
+        if self._redoc_js_url is not None:
+            redoc_asset_kwargs["redoc_js_url"] = self._redoc_js_url
+        if self._redoc_favicon_url is not None:
+            redoc_asset_kwargs["redoc_favicon_url"] = self._redoc_favicon_url
+
+        @router.get(redoc_url, include_in_schema=False)
+        async def get_redoc(request: Request) -> HTMLResponse:
+            root_path = request.scope.get("root_path", "").rstrip("/")
+            versioned_openapi_url = f"{root_path}{version_prefix}{openapi_url}"
+            return get_redoc_html(openapi_url=versioned_openapi_url, title=title, **redoc_asset_kwargs)
+
+    def _add_versions_route(self, versions: list[VersionT]) -> None:
+        @self._app.get("/versions", tags=["Versions"], response_class=JSONResponse)
+        def get_versions(request: Request) -> dict[str, Any]:
+            root_path = request.scope.get("root_path", "").rstrip("/")
+            version_models: list[dict[str, Any]] = []
+            for version in versions:
+                version_prefix = self._format_string(self._prefix_format, version)
+                doc_version_str = self._format_string(self._semantic_version_format, version)
+
+                version_model = {"version": doc_version_str}
+
+                if self._include_version_openapi_route and self._app.openapi_url is not None:
+                    version_model["openapi_url"] = f"{root_path}{version_prefix}{self._app.openapi_url}"
+                if self._include_version_docs and self._docs_url is not None:
+                    version_model["swagger_url"] = f"{root_path}{version_prefix}{self._docs_url}"
+                if self._include_version_docs and self._redoc_url is not None:
+                    version_model["redoc_url"] = f"{root_path}{version_prefix}{self._redoc_url}"
+
+                version_models.append(version_model)
+
+            return {"versions": version_models}
+
+    def _add_route_to_router(self, route: Any, router: APIRouter, version: VersionT) -> None:
+        # Read attributes from the original route, not the RouteContext proxy. The proxy
+        # (FastAPI >= 0.137.2) only merges path/tags/deps; other fields such as
+        # response_model, status_code, and operation_id would be silently lost.
+        source_route = _unwrap_route(route)
+        add_method: Callable[..., Any]
+
+        if isinstance(source_route, APIRoute):
+            add_method = router.add_api_route
+        elif isinstance(source_route, APIWebSocketRoute):
+            add_method = router.add_api_websocket_route
+        else:
+            raise TypeError(f"Unsupported route type: {type(source_route).__name__}")
+
+        valid_params = inspect.signature(add_method).parameters.keys()
+        filtered_kwargs = {k: getattr(source_route, k) for k in valid_params if hasattr(source_route, k)}
+        filtered_kwargs.setdefault("endpoint", source_route.endpoint)
+        # Override path/tags/deps with the merged values from RouteContext when present.
+        for merged_attr in ("path", "tags", "dependencies"):
+            if hasattr(route, merged_attr) and merged_attr in valid_params:
+                filtered_kwargs[merged_attr] = getattr(route, merged_attr)
+
+        deprecated_in_version = self._extract_version_attribute(route.endpoint, _ATTR_DEPRECATE_IN, route.path)
+        if deprecated_in_version is not None:
+            if isinstance(version, tuple) and isinstance(deprecated_in_version, tuple):
+                if version >= deprecated_in_version:
+                    filtered_kwargs["deprecated"] = True
+            elif isinstance(version, str) and isinstance(deprecated_in_version, str):
+                if version >= deprecated_in_version:
+                    filtered_kwargs["deprecated"] = True
+
+        # An empty string name causes an internal FastAPI error; drop it to use the default.
+        if "name" in filtered_kwargs and not filtered_kwargs["name"]:
+            filtered_kwargs.pop("name")
+
+        add_method(**filtered_kwargs)

fastapi_router_versioning-0.1.0.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: fastapi-router-versioning
+Version: 0.1.0
+Summary: Native, router-based API versioning for FastAPI, featuring per-version docs and a declarative route lifecycle.
+Project-URL: Homepage, https://github.com/mat81black/fastapi-router-versioning
+Project-URL: Repository, https://github.com/mat81black/fastapi-router-versioning
+Project-URL: Issues, https://github.com/mat81black/fastapi-router-versioning/issues
+Author-email: Matteo Nieddu <mat81black@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi!=0.137.0,!=0.137.1,>=0.120.0
+Description-Content-Type: text/markdown
+
+# FastAPI Router Versioning (Native API Versioning)
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-router-versioning)](https://pypi.org/project/fastapi-router-versioning/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-router-versioning)](https://pypi.org/project/fastapi-router-versioning/)
+
+The native, router-based solution for **API versioning in FastAPI**.
+
+If you want to implement **FastAPI API versioning**, you can simply annotate your routes with `@api_version`, call `.versionize()`, and get isolated URL prefixes, per-version Swagger UI, and a full route lifecycle — all without touching your existing application structure.
+
+---
+
+## Features
+
+- **SemVer and CalVer** — version routes with `(major, minor)` tuples or arbitrary strings
+- **Per-version docs** — isolated Swagger UI, ReDoc, and `openapi.json` for every version
+- **Declarative lifecycle** — introduce, deprecate, and remove routes with a single decorator
+- **Latest alias** — serve the newest version under a stable `/latest` prefix
+- **Self-hosted docs** — point Swagger UI and ReDoc at your own assets for air-gapped environments
+- **Reverse proxy aware** — doc URLs include the ASGI `root_path` at request time, so sub-app mounting works out of the box
+- **Broad compatibility** — works with nested routers, WebSockets, `Depends`, and OpenAPI Callbacks
+
+---
+
+## Requirements
+
+- Python ≥ 3.10
+- FastAPI ≥ 0.120.0
+
+---
+
+## Installation
+
+```bash
+pip install fastapi-router-versioning
+# or
+uv add fastapi-router-versioning
+```
+
+---
+
+## Quick start — SemVer
+
+```python
+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()
+# Mounts: GET /v1_0/items   GET /v2_0/items
+```
+
+Each version also gets its own Swagger UI at `/v1_0/docs`, `/v2_0/docs`, and so on.
+
+---
+
+## Quick start — CalVer
+
+```python
+from fastapi import APIRouter, FastAPI
+from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
+
+app = FastAPI()
+router = APIRouter()
+
+
+@router.get("/items")
+@api_version("2025-01-01")
+def get_items():
+    return {"release": "2025-01-01"}
+
+
+RouterVersioner(app=app, routers=router, version_format=VersionFormat.CALVER).versionize()
+# Mounts: GET /2025-01-01/items
+```
+
+Any string is a valid CalVer token: `"2025-01-01"`, `"v3"`, `"stable"`, etc.
+
+> **CalVer sorting:** versions are sorted lexicographically, so strings must be comparable in the intended order. ISO dates (`"2025-01-01"`) and zero-padded numbers (`"v01"`, `"v02"`) work correctly. Strings like `"v1"`, `"v10"`, `"v2"` will **not** sort correctly and will cause routes to appear in the wrong versions.
+
+---
+
+## Route lifecycle
+
+Use `deprecate_in` and `remove_in` to manage the full lifecycle of a route across versions.
+
+```python
+@router.get("/legacy")
+@api_version((1, 0), deprecate_in=(2, 0), remove_in=(3, 0))
+def legacy_route():
+    return {"msg": "I am stable in v1, deprecated in v2, gone in v3."}
+```
+
+| Version | `/legacy` present? | Marked deprecated? |
+|---------|-------------------|--------------------|
+| v1.0    | yes               | no                 |
+| v2.0    | yes               | **yes**            |
+| v3.0    | **no**            | —                  |
+
+Routes without `@api_version` fall back to `default_version` (default: `(1, 0)` for SemVer, `"1"` for CalVer).
+
+---
+
+## `RouterVersioner` reference
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `app` | `FastAPI` | required | The FastAPI application instance |
+| `routers` | `APIRouter \| list[APIRouter]` | required | Router(s) whose routes will be versioned |
+| `version_format` | `VersionFormat` | `SEMVER` | Versioning strategy (`SEMVER` or `CALVER`) |
+| `prefix_format` | `str \| None` | `/v{major}_{minor}` / `/{version}` | URL prefix template; supports `{major}`, `{minor}`, `{version}` |
+| `semantic_version_format` | `str \| None` | `{major}.{minor}` / `{version}` | Version label used in Swagger/ReDoc titles |
+| `default_version` | `VersionT \| None` | `(1, 0)` / `"1"` | Fallback version for routes without `@api_version` |
+| `latest_prefix` | `str \| None` | `None` | If set, adds an alias prefix (e.g. `"/latest"`) pointing to the newest version |
+| `include_version_docs` | `bool` | `True` | Create per-version Swagger UI and ReDoc pages |
+| `include_version_openapi_route` | `bool` | `True` | Create a per-version `openapi.json` route |
+| `include_versions_route` | `bool` | `False` | Add a `GET /versions` endpoint listing all active versions |
+| `sort_routes` | `bool` | `False` | Sort routes alphabetically by path within each version |
+| `callback` | `Callable[[APIRouter, VersionT, str], None] \| None` | `None` | Hook called once per versioned router, before it is included in the app |
+| `webhook_routers` | `APIRouter \| list[APIRouter] \| None` | `None` | Router(s) containing webhook definitions annotated with `@api_version`; each version's schema shows only the webhooks active in that version |
+| `openapi_hook` | `Callable[[dict, VersionT], dict] \| None` | `None` | Hook applied to the generated OpenAPI schema for each version; receives `(schema, version)` and must return the modified schema |
+| `swagger_js_url` | `str \| None` | FastAPI CDN | Custom URL for the Swagger UI JS bundle |
+| `swagger_css_url` | `str \| None` | FastAPI CDN | Custom URL for the Swagger UI CSS |
+| `swagger_favicon_url` | `str \| None` | FastAPI favicon | Custom URL for the Swagger UI favicon |
+| `redoc_js_url` | `str \| None` | FastAPI CDN | Custom URL for the ReDoc JS bundle |
+| `redoc_favicon_url` | `str \| None` | FastAPI favicon | Custom URL for the ReDoc favicon |
+| `redoc_with_google_fonts` | `bool` | `True` | If `False`, ReDoc will not load Google Fonts |
+
+Call `.versionize()` after constructing the object. It returns the list of active versions.
+
+---
+
+## `@api_version` reference
+
+```python
+@api_version(version, *, deprecate_in=None, remove_in=None)
+```
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `version` | `tuple[int, int] \| str` | yes | Version when this route is introduced |
+| `deprecate_in` | same \| `None` | no | Version when this route is marked deprecated in the docs |
+| `remove_in` | same \| `None` | no | Version from which this route is removed entirely |
+
+All three parameters must match the `version_format` configured on `RouterVersioner`
+(`tuple[int, int]` for SemVer, `str` for CalVer).
+
+---
+
+## Advanced options
+
+### Latest alias
+
+Serve the newest version under a stable prefix that clients can pin to:
+
+```python
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    latest_prefix="/latest",
+).versionize()
+# Also mounts /latest/... pointing to the highest version
+```
+
+### Version discovery endpoint
+
+```python
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    include_versions_route=True,
+).versionize()
+```
+
+```json
+GET /versions
+{
+  "versions": [
+    {
+      "version": "1.0",
+      "openapi_url": "/v1_0/openapi.json",
+      "swagger_url": "/v1_0/docs",
+      "redoc_url": "/v1_0/redoc"
+    }
+  ]
+}
+```
+
+### Custom URL format
+
+Use `prefix_format` and `semantic_version_format` to control how versions appear in URLs and docs.
+
+**Major-only versioning** (`/v1`, `/v2`, `/v3`):
+
+```python
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    prefix_format="/v{major}",
+    semantic_version_format="{major}",
+    latest_prefix="/latest",
+).versionize()
+# Mounts: GET /v1/items   GET /v2/items   GET /latest/items
+# Swagger at /v1/docs, /v2/docs — titles show "v1", "v2"
+```
+
+The route decorator still uses `(major, minor)` tuples — only the URL and doc label change.
+
+### OpenAPI schema hook
+
+`openapi_hook` lets you modify the generated OpenAPI JSON for each version — useful for
+custom extensions, logos, version-specific metadata, or AWS API Gateway integration.
+Unlike overriding `app.openapi`, this hook is called inside the per-version generation
+pipeline, so it receives the correct filtered schema.
+
+```python
+def my_openapi_hook(schema: dict, version: tuple[int, int]) -> dict:
+    # Applied to every version
+    schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
+
+    # Applied only to v1
+    if version == (1, 0):
+        schema["info"]["description"] += "\n\n**DEPRECATED:** Use v2."
+
+    return schema
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    openapi_hook=my_openapi_hook,
+).versionize()
+```
+
+The hook receives `(schema: dict, version: VersionT)` and must return the (modified) dict.
+
+### OpenAPI Callbacks and Webhooks
+
+**Callbacks** (per-route) are propagated automatically — any `callbacks=[...]` parameter
+on a route is copied to every versioned copy of that route:
+
+```python
+callback_router = APIRouter()
+
+@callback_router.post("{$url}")
+def on_event(body: dict) -> None: ...
+
+@router.post("/items", callbacks=callback_router.routes)
+@api_version((1, 0))
+def create_item() -> dict: ...
+```
+
+**Webhooks** (`app.webhooks`) appear in the OpenAPI schema of every version by default.
+To version webhooks independently, use `webhook_routers` with the same `@api_version`
+decorator used on regular routes:
+
+```python
+webhook_router = APIRouter()
+
+@webhook_router.post("/order-created")
+@api_version((1, 0))
+def webhook_order_v1(body: OrderV1) -> None: ...
+
+@webhook_router.post("/order-created")
+@api_version((2, 0))       # replaces v1 definition (same path + method)
+def webhook_order_v2(body: OrderV2) -> None: ...
+
+@webhook_router.post("/payment-failed")
+@api_version((1, 0), remove_in=(2, 0))
+def webhook_payment_v1(body: dict) -> None: ...
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    webhook_routers=webhook_router,
+    version_format=VersionFormat.SEMVER,
+).versionize()
+# /v1_0/openapi.json → webhooks: /order-created (V1), /payment-failed
+# /v2_0/openapi.json → webhooks: /order-created (V2)  ← /payment-failed removed
+```
+
+The same introduce / `remove_in` lifecycle applies. Webhook versions follow route versions:
+a new webhook version only appears once a route version creates that API prefix.
+
+### Multiple routers
+
+Pass a list of routers to version routes that are split across modules:
+
+```python
+RouterVersioner(
+    app=app,
+    routers=[users_router, products_router],
+    version_format=VersionFormat.SEMVER,
+).versionize()
+```
+
+All routers are versioned together under the same prefix tree.
+
+### Self-hosted docs (air-gapped environments)
+
+By default, Swagger UI and ReDoc assets are loaded from the FastAPI CDN. In air-gapped or corporate environments, point them at assets you host yourself:
+
+```python
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    swagger_js_url="/static/swagger-ui-bundle.js",
+    swagger_css_url="/static/swagger-ui.css",
+    swagger_favicon_url="/static/favicon.png",
+    redoc_js_url="/static/redoc.standalone.js",
+    redoc_favicon_url="/static/favicon.png",
+    redoc_with_google_fonts=False,
+).versionize()
+```
+
+See [`examples/download_static_assets.py`](examples/download_static_assets.py) for a ready-made script that downloads all required assets in one step, and [`examples/self_hosted_docs_app.py`](examples/self_hosted_docs_app.py) for a complete working example.
+
+### Reverse proxy / sub-app mounting
+
+When the app runs behind a reverse proxy or is mounted as a sub-application, the ASGI `root_path` is included in all per-version doc URLs automatically — no extra configuration needed:
+
+```python
+parent = FastAPI()
+parent.mount("/api", app)  # root_path="/api" is injected at request time
+# /api/v1_0/docs correctly references /api/v1_0/openapi.json
+```
+
+### Callback hook
+
+Run custom logic each time a versioned router is created — useful for logging or metrics:
+
+```python
+def on_version_created(router: APIRouter, version, prefix: str) -> None:
+    print(f"Registered version {version} at {prefix}")
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    callback=on_version_created,
+).versionize()
+```
+
+---
+
+## Examples
+
+Runnable examples are available in the [`examples/`](examples/) directory:
+
+| File | What it shows |
+|---|---|
+| [`semver_app.py`](examples/semver_app.py) | Full SemVer lifecycle (introduce, deprecate, remove) |
+| [`calver_app.py`](examples/calver_app.py) | Same lifecycle with CalVer date strings |
+| [`semver_major_only_app.py`](examples/semver_major_only_app.py) | Custom prefix `/v1`, `/v2` via `prefix_format` |
+| [`webhook_versioning_app.py`](examples/webhook_versioning_app.py) | Per-version webhook definitions via `webhook_routers` |
+| [`multi_router_app.py`](examples/multi_router_app.py) | Multiple routers versioned together |
+| [`self_hosted_docs_app.py`](examples/self_hosted_docs_app.py) | Swagger UI and ReDoc from local static assets |
+
+---
+
+## License
+
+[MIT](LICENSE)

fastapi_router_versioning-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+fastapi_router_versioning/__init__.py,sha256=HEfhSE-ggX7QJX8vOQiUGNRhnKg2VcBUY5eds9ReD3c,175
+fastapi_router_versioning/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_router_versioning/versioner.py,sha256=9xBQCB_snF9pDXaCAh95IDKQ2Js_JAFVzU24zjZ7RO4,26437
+fastapi_router_versioning-0.1.0.dist-info/METADATA,sha256=gBtOBWdNZrVaR_oDlg0w0-wMeRVoBynBnGRKD_Z7Rvo,14710
+fastapi_router_versioning-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fastapi_router_versioning-0.1.0.dist-info/licenses/LICENSE,sha256=Tsif_IFIW5f-xYSy1KlhAy7v_oNEU4lP2cEnSQbMdE4,1086
+fastapi_router_versioning-0.1.0.dist-info/RECORD,,

fastapi_router_versioning-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_router_versioning-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Sebastián Ramírez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.