fastapi-router-versioning 0.2.1__tar.gz → 0.2.2__tar.gz

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-router-versioning
-Version: 0.2.1
+Version: 0.2.2
 Summary: Router-based API versioning for FastAPI, with 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
@@ -400,6 +400,23 @@ RouterVersioner(
 ).versionize()
 ```
 
+The app's own root `/docs`, `/redoc`, and `/openapi.json` (not versioned) also reflect
+`validation_error_code` — RouterVersioner patches `app.openapi()` itself, so nothing needs to
+be disabled to get consistent schemas everywhere.
+
+**If you do share one app across multiple `RouterVersioner` instances** — the only case this is
+actually needed for is mixing `version_format` (e.g. SemVer for one group of routes, CalVer for
+another) on the same app, since a single instance already handles multiple routers and prefixes
+via `routers=[...]` (see [`multi_router_app.py`](examples/multi_router_app.py)). All instances
+must use the same `validation_error_code` when `handle_validation_exceptions=True` — since
+FastAPI's exception handler is app-wide, not per-router, a mismatch raises `RuntimeError` at
+construction time instead of silently picking whichever was registered first. Each instance
+must also use a distinct `prefix_format`/`latest_prefix`, otherwise their docs/openapi routes
+would collide at the same path — this also raises `RuntimeError`.
+
+For genuine module independence (separate `validation_error_code`, no risk of prefix collisions,
+isolated docs), mount each module as its own FastAPI sub-application instead — see below.
+
 ### 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:
@@ -410,6 +427,10 @@ parent.mount("/api", app)  # root_path="/api" is injected at request time
 # /api/v1_0/docs correctly references /api/v1_0/openapi.json
 ```
 
+Each sub-application has its own independent `RouterVersioner`, `app.state`, and OpenAPI docs —
+no coordination needed between them, including different `validation_error_code` per
+sub-application. See [`examples/mounted_subapps_app.py`](examples/mounted_subapps_app.py).
+
 ### Callback hook
 
 Run custom logic each time a versioned router is created — useful for logging or metrics:
@@ -442,6 +463,7 @@ Runnable examples are available in the [`examples/`](examples/) directory:
 | [`self_hosted_docs_app.py`](examples/self_hosted_docs_app.py) | Swagger UI and ReDoc from local static assets |
 | [`validation_error_code_app.py`](examples/validation_error_code_app.py) | Return `400` instead of `422` for validation errors (automatic handler via `RouterVersioner`) |
 | [`validation_error_code_custom_handler_app.py`](examples/validation_error_code_custom_handler_app.py) | Same, but with `handle_validation_exceptions=False` and a user-defined exception handler |
+| [`mounted_subapps_app.py`](examples/mounted_subapps_app.py) | Independently versioned modules as separate FastAPI sub-applications via `app.mount()` |
 
 ---
 

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/README.md

@@ -371,6 +371,23 @@ RouterVersioner(
 ).versionize()
 ```
 
+The app's own root `/docs`, `/redoc`, and `/openapi.json` (not versioned) also reflect
+`validation_error_code` — RouterVersioner patches `app.openapi()` itself, so nothing needs to
+be disabled to get consistent schemas everywhere.
+
+**If you do share one app across multiple `RouterVersioner` instances** — the only case this is
+actually needed for is mixing `version_format` (e.g. SemVer for one group of routes, CalVer for
+another) on the same app, since a single instance already handles multiple routers and prefixes
+via `routers=[...]` (see [`multi_router_app.py`](examples/multi_router_app.py)). All instances
+must use the same `validation_error_code` when `handle_validation_exceptions=True` — since
+FastAPI's exception handler is app-wide, not per-router, a mismatch raises `RuntimeError` at
+construction time instead of silently picking whichever was registered first. Each instance
+must also use a distinct `prefix_format`/`latest_prefix`, otherwise their docs/openapi routes
+would collide at the same path — this also raises `RuntimeError`.
+
+For genuine module independence (separate `validation_error_code`, no risk of prefix collisions,
+isolated docs), mount each module as its own FastAPI sub-application instead — see below.
+
 ### 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:
@@ -381,6 +398,10 @@ parent.mount("/api", app)  # root_path="/api" is injected at request time
 # /api/v1_0/docs correctly references /api/v1_0/openapi.json
 ```
 
+Each sub-application has its own independent `RouterVersioner`, `app.state`, and OpenAPI docs —
+no coordination needed between them, including different `validation_error_code` per
+sub-application. See [`examples/mounted_subapps_app.py`](examples/mounted_subapps_app.py).
+
 ### Callback hook
 
 Run custom logic each time a versioned router is created — useful for logging or metrics:
@@ -413,6 +434,7 @@ Runnable examples are available in the [`examples/`](examples/) directory:
 | [`self_hosted_docs_app.py`](examples/self_hosted_docs_app.py) | Swagger UI and ReDoc from local static assets |
 | [`validation_error_code_app.py`](examples/validation_error_code_app.py) | Return `400` instead of `422` for validation errors (automatic handler via `RouterVersioner`) |
 | [`validation_error_code_custom_handler_app.py`](examples/validation_error_code_custom_handler_app.py) | Same, but with `handle_validation_exceptions=False` and a user-defined exception handler |
+| [`mounted_subapps_app.py`](examples/mounted_subapps_app.py) | Independently versioned modules as separate FastAPI sub-applications via `app.mount()` |
 
 ---
 

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/RELEASE_NOTES.md

@@ -2,6 +2,21 @@
 
 ## Latest Changes
 
+## 0.2.2 (2026-07-01)
+
+### Fixes
+
+* 🐛 Fix root OpenAPI schema not reflecting validation_error_code. PR [#21](https://github.com/mat81black/fastapi-router-versioning/pull/21) by [@mat81black](https://github.com/mat81black).
+* 🐛 Fix silent conflicts from misconfigured RouterVersioner instances sharing an app. PR [#20](https://github.com/mat81black/fastapi-router-versioning/pull/20) by [@mat81black](https://github.com/mat81black).
+
+### Internal
+
+* 👷 Add a regression test for `RouterVersioner` under a real `app.mount()` sub-application, and `examples/mounted_subapps_app.py` demonstrating the same scenario. PR [#22](https://github.com/mat81black/fastapi-router-versioning/pull/22) by [@mat81black](https://github.com/mat81black).
+
+### Refactors
+
+* ♻️ Reorder RouterVersioner methods to match their call graph. PR [#23](https://github.com/mat81black/fastapi-router-versioning/pull/23) by [@mat81black](https://github.com/mat81black).
+
 ## 0.2.1 (2026-06-26)
 
 ### Fixes

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/examples/calver_app.py

@@ -1,4 +1,5 @@
 from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
 
 from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
 
@@ -10,6 +11,11 @@ app = FastAPI(
 router = APIRouter()
 
 
+class CreateItemRequest(BaseModel):
+    name: str
+    quantity: int
+
+
 # 1. Introduced in the January release, persists across all versions
 @router.get("/persistent")
 @api_version("2025-01-01")
@@ -41,6 +47,14 @@ def future_route() -> dict[str, str]:
     return {"status": "active", "message": "Welcome to the December release!"}
 
 
+# POST /items with an invalid "quantity" (e.g. "not-a-number") returns FastAPI's
+# default 422 validation error.
+@router.post("/items")
+@api_version("2025-01-01")
+def create_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
 versioner = RouterVersioner(
     app=app,
     routers=router,

fastapi_router_versioning-0.2.2/examples/mounted_subapps_app.py

@@ -0,0 +1,76 @@
+"""
+Sub-applications example.
+
+Shows how to mount independently versioned modules as separate FastAPI
+sub-applications via app.mount() — each with its own RouterVersioner, docs,
+and OpenAPI schema. RouterVersioner already threads the ASGI root_path through
+docs/openapi URLs automatically, so no extra configuration is needed.
+"""
+
+from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
+
+from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
+
+
+class CreateItemRequest(BaseModel):
+    name: str
+    quantity: int
+
+
+main_app = FastAPI(title="Main App")
+
+# ── Admin sub-app: SemVer, validation errors return 400 ──────────────────────
+
+admin_app = FastAPI(title="Admin API")
+admin_router = APIRouter()
+
+
+@admin_router.get("/users")
+@api_version((1, 0))
+def list_admin_users() -> dict[str, list[str]]:
+    return {"users": []}
+
+
+@admin_router.post("/items")
+@api_version((1, 0))
+def create_admin_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
+RouterVersioner(
+    app=admin_app, routers=admin_router, version_format=VersionFormat.SEMVER, validation_error_code=400
+).versionize()
+
+
+# ── Orders sub-app: CalVer ────────────────────────────────────────────────────
+
+orders_app = FastAPI(title="Orders API")
+orders_router = APIRouter()
+
+
+@orders_router.get("/")
+@api_version("2025-01-01")
+def list_orders() -> dict[str, list[str]]:
+    return {"orders": []}
+
+
+@orders_router.post("/items")
+@api_version("2025-01-01")
+def create_order_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
+RouterVersioner(app=orders_app, routers=orders_router, version_format=VersionFormat.CALVER).versionize()
+
+
+# ── Mount both sub-apps on the main app ───────────────────────────────────────
+
+main_app.mount("/admin", admin_app)
+main_app.mount("/orders", orders_app)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(main_app, host="127.0.0.1", port=8009)

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/examples/multi_router_app.py

@@ -8,6 +8,7 @@ versioned together under a single prefix tree.
 """
 
 from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
 
 from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
 
@@ -20,6 +21,11 @@ users_router = APIRouter(prefix="/users", tags=["Users"])
 products_router = APIRouter(prefix="/products", tags=["Products"])
 
 
+class CreateProductRequest(BaseModel):
+    name: str
+    quantity: int
+
+
 @users_router.get("/")
 @api_version((1, 0))
 def list_users() -> dict[str, list[str]]:
@@ -44,6 +50,14 @@ def search_products() -> dict[str, list[str]]:
     return {"results": []}
 
 
+# POST /products with an invalid "quantity" (e.g. "not-a-number") returns FastAPI's
+# default 422 validation error.
+@products_router.post("/")
+@api_version((1, 0))
+def create_product(body: CreateProductRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
 versioner = RouterVersioner(
     app=app,
     routers=[users_router, products_router],  # list of routers versioned together

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/examples/openapi_hook_app.py

@@ -1,6 +1,7 @@
 from typing import Any
 
 from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
 
 from fastapi_router_versioning import RouterVersioner, VersionFormat, VersionT, api_version
 
@@ -12,6 +13,11 @@ app = FastAPI(
 router = APIRouter()
 
 
+class CreateItemRequest(BaseModel):
+    name: str
+    quantity: int
+
+
 @router.get("/items")
 @api_version((1, 0))
 def get_items_v1() -> dict[str, object]:
@@ -30,6 +36,14 @@ def get_users() -> dict[str, object]:
     return {"users": ["alice", "bob"]}
 
 
+# POST /items with an invalid "quantity" (e.g. "not-a-number") returns FastAPI's
+# default 422 validation error.
+@router.post("/items")
+@api_version((1, 0))
+def create_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
 def my_openapi_hook(schema: dict[str, Any], version: VersionT) -> dict[str, Any]:
     # Applied to every version: add a company logo to the docs
     schema["info"]["x-logo"] = {"url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"}

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/examples/self_hosted_docs_app.py

@@ -18,6 +18,7 @@ from pathlib import Path
 
 from fastapi import APIRouter, FastAPI
 from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
 
 from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
 
@@ -32,12 +33,25 @@ app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
 router = APIRouter()
 
 
+class CreateItemRequest(BaseModel):
+    name: str
+    quantity: int
+
+
 @router.get("/items")
 @api_version((1, 0))
 def list_items() -> dict[str, list[str]]:
     return {"items": []}
 
 
+# POST /items with an invalid "quantity" (e.g. "not-a-number") returns FastAPI's
+# default 422 validation error.
+@router.post("/items")
+@api_version((1, 0))
+def create_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
 versioner = RouterVersioner(
     app=app,
     routers=router,

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/examples/semver_app.py

@@ -1,4 +1,5 @@
 from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
 
 from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
 
@@ -10,6 +11,11 @@ app = FastAPI(
 router = APIRouter()
 
 
+class CreateItemRequest(BaseModel):
+    name: str
+    quantity: int
+
+
 # 1. Introduced in v1.0, persists across all versions
 @router.get("/persistent")
 @api_version((1, 0))
@@ -41,6 +47,14 @@ def future_route() -> dict[str, str]:
     return {"status": "active", "message": "Welcome to v3.0!"}
 
 
+# POST /items with an invalid "quantity" (e.g. "not-a-number") returns FastAPI's
+# default 422 validation error.
+@router.post("/items")
+@api_version((1, 0))
+def create_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
 versioner = RouterVersioner(
     app=app,
     routers=router,

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/examples/semver_major_only_app.py

@@ -1,4 +1,5 @@
 from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
 
 from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
 
@@ -10,6 +11,11 @@ app = FastAPI(
 router = APIRouter()
 
 
+class CreateItemRequest(BaseModel):
+    name: str
+    quantity: int
+
+
 # 1. Introduced in v1, persists across all versions
 @router.get("/persistent")
 @api_version((1, 0))
@@ -41,6 +47,14 @@ def future_route() -> dict[str, str]:
     return {"status": "active", "message": "Welcome to v3!"}
 
 
+# POST /items with an invalid "quantity" (e.g. "not-a-number") returns FastAPI's
+# default 422 validation error.
+@router.post("/items")
+@api_version((1, 0))
+def create_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
 versioner = RouterVersioner(
     app=app,
     routers=router,

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/examples/webhook_versioning_app.py

@@ -1,4 +1,5 @@
 from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel
 
 from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
 
@@ -12,6 +13,11 @@ app = FastAPI(
 router = APIRouter()
 
 
+class CreateItemRequest(BaseModel):
+    name: str
+    quantity: int
+
+
 @router.post("/orders")
 @api_version((1, 0))
 def create_order_v1() -> dict[str, str]:
@@ -30,6 +36,14 @@ def get_items() -> dict[str, object]:
     return {"items": ["a", "b"]}
 
 
+# POST /items with an invalid "quantity" (e.g. "not-a-number") returns FastAPI's
+# default 422 validation error.
+@router.post("/items")
+@api_version((1, 0))
+def create_item(body: CreateItemRequest) -> dict[str, str]:
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
 # --- Webhook definitions ---
 # Webhooks document outbound calls your API makes to subscriber URLs.
 # Annotate them with @api_version just like regular routes.

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/fastapi_router_versioning/__init__.py

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

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/fastapi_router_versioning/versioner.py

@@ -25,37 +25,6 @@ from starlette.requests import Request
 _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
-        elif isinstance(original, APIWebSocketRoute):
-            # For WebSockets, RouteContext.__getattr__ does NOT merge parent prefixes into path.
-            # _route_context._EffectiveRouteContext holds the fully resolved starlette_route
-            # (with all include_router prefixes applied). Fall back to original for direct routes.
-            rc = getattr(route_ctx, "_route_context", None)
-            starlette_route = getattr(rc, "starlette_route", None) if rc is not None else None
-            yield starlette_route if starlette_route is not None else original
-        else:
-            yield original  # pragma: no cover
-
-
-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
@@ -228,6 +197,7 @@ class RouterVersioner:
 
         if self._validation_error_code != 422 and self._handle_validation_exceptions:
             self._register_validation_exception_handler()
+            self._patch_root_openapi()
 
     def _validate_version_type(self, version: Any, route_path: str) -> None:
         if self._version_format == VersionFormat.SEMVER:
@@ -239,12 +209,134 @@ class RouterVersioner:
                 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)
 
+    def _register_validation_exception_handler(self) -> None:
+        existing_code = getattr(self._app.state, "_validation_effective_code", None)
+        if existing_code is not None:
+            if existing_code != self._validation_error_code:
+                raise RuntimeError(
+                    f"A validation exception handler is already registered on this app with status "
+                    f"code {existing_code}, which conflicts with the requested {self._validation_error_code}. "
+                    "All RouterVersioner instances with handle_validation_exceptions=True sharing the "
+                    "same app must use the same validation_error_code."
+                )
+            return  # same code already registered: idempotent
+
+        @self._app.exception_handler(RequestValidationError)
+        async def custom_validation_exception_handler(_request: Request, exc: RequestValidationError) -> JSONResponse:
+            return JSONResponse(
+                status_code=self._validation_error_code,
+                content={"detail": jsonable_encoder(exc.errors())},
+            )
+
+        self._app.state._validation_effective_code = self._validation_error_code
+
+    def _patch_root_openapi(self) -> None:
+        if getattr(self._app.state, "_root_openapi_patched", False):
+            return
+
+        original_openapi = self._app.openapi
+
+        def custom_openapi() -> dict[str, Any]:
+            schema = original_openapi()
+            self._patch_validation_error_openapi(schema)
+            self._app.openapi_schema = schema
+            return schema
+
+        self._app.openapi = custom_openapi  # type: ignore[method-assign] # ty:ignore[invalid-assignment]
+        self._app.state._root_openapi_patched = True
+
+    def _get_schema_validation_code(self) -> int:
+        if not self._handle_validation_exceptions:
+            return self._validation_error_code
+        return getattr(self._app.state, "_validation_effective_code", self._validation_error_code)
+
+    def _patch_validation_error_openapi(self, schema: dict[str, Any]) -> None:
+        target = self._get_schema_validation_code()
+        if target == 422:
+            return
+
+        target_code = str(target)
+        http_methods = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+
+        for _path, path_item in schema.get("paths", {}).items():
+            for _method, operation in path_item.items():
+                if _method not in http_methods:
+                    continue
+
+                responses = operation.get("responses", {})
+                if "422" in responses:
+                    response_422 = responses["422"]
+                    content_422 = response_422.get("content", {}).get("application/json", {})
+                    schema_422 = content_422.get("schema", {})
+                    ref = schema_422.get("$ref", "")
+
+                    if ref.endswith("HTTPValidationError"):
+                        if target_code in responses:
+                            existing_response = responses[target_code]
+                            existing_content = existing_response.setdefault("content", {}).setdefault(
+                                "application/json", {}
+                            )
+                            existing_schema = existing_content.setdefault("schema", {})
+
+                            if "anyOf" in existing_schema:
+                                existing_schema["anyOf"].append(schema_422)
+                            elif existing_schema:
+                                existing_content["schema"] = {"anyOf": [existing_schema, schema_422]}
+                            else:
+                                existing_content["schema"] = schema_422
+
+                            old_desc = existing_response.get("description", "Error")
+                            existing_response["description"] = f"{old_desc} / Validation Error"
+
+                            del responses["422"]
+                        else:
+                            responses[target_code] = responses.pop("422")
+
     @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)
 
+    @staticmethod
+    def _version_gte(a: VersionT, b: VersionT) -> bool:
+        if isinstance(a, tuple) and isinstance(b, tuple):
+            return a >= b
+        if isinstance(a, str) and isinstance(b, str):
+            return a >= b
+        return False
+
+    @staticmethod
+    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
+            elif isinstance(original, APIWebSocketRoute):
+                # For WebSockets, RouteContext.__getattr__ does NOT merge parent prefixes into path.
+                # _route_context._EffectiveRouteContext holds the fully resolved starlette_route
+                # (with all include_router prefixes applied). Fall back to original for direct routes.
+                rc = getattr(route_ctx, "_route_context", None)
+                starlette_route = getattr(rc, "starlette_route", None) if rc is not None else None
+                yield starlette_route if starlette_route is not None else original
+            else:
+                yield original  # pragma: no cover
+
+    @staticmethod
+    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)
+
     def _extract_version_attribute(self, endpoint: Any, attribute: str, route_path: str) -> VersionT | None:
         val = getattr(endpoint, attribute, None)
         if isinstance(val, (tuple, str)):
@@ -263,6 +355,7 @@ class RouterVersioner:
 
         for version, routes_by_key in routes_by_version.items():
             version_prefix = self._format_string(self._prefix_format, version)
+            self._claim_prefix(version_prefix)
             active_webhooks = self._resolve_webhooks_for_version(version, webhooks_by_version)
 
             version_router = self._build_version_router(
@@ -279,6 +372,7 @@ class RouterVersioner:
             latest_webhooks = active_webhooks
 
         if self._latest_prefix is not None and latest_version is not None:
+            self._claim_prefix(self._latest_prefix)
             latest_router = self._build_version_router(
                 version=latest_version,
                 version_prefix=self._latest_prefix,
@@ -294,59 +388,56 @@ class RouterVersioner:
 
         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)
+    @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 = cls._unwrap_route(route)
 
-        self._add_version_docs(router=router, version=version, version_prefix=version_prefix, webhooks=webhooks)
+        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 router
+        return routes_by_key
 
-    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))
+    def _resolve_lifecycle(self, routes: list[Any]) -> dict[VersionT, dict[tuple[str, str], Any]]:
+        """Accumulates active routes per version, honoring @api_version introduce/remove.
 
-        routes_introduced: dict[VersionT, list[Any]] = defaultdict(list)
-        for route in all_routes:
+        Shared by _get_routes_by_version and _get_webhooks_by_version: both need the same
+        introduce/remove bookkeeping, only the input route list and output shape differ.
+        """
+        introduced: dict[VersionT, list[Any]] = defaultdict(list)
+        for route in 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)
+            introduced[start_version if start_version is not None else self._default_version].append(route)
 
-        routes_removed: dict[VersionT, list[Any]] = defaultdict(list)
-        for route in all_routes:
+        removed: dict[VersionT, list[Any]] = defaultdict(list)
+        for route in 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] = {}
+                removed[end_version].append(route)
 
-        for version in versions:
-            for route in routes_introduced[version]:
-                active_routes.update(self._get_route_keys(route=route))
+        active: dict[tuple[str, str], Any] = {}
+        result: dict[VersionT, dict[tuple[str, str], Any]] = {}
 
-            for route in routes_removed.get(version, []):
+        for version in sorted(set(introduced.keys()) | set(removed.keys())):
+            for route in introduced[version]:
+                active.update(self._get_route_keys(route=route))
+            for route in removed.get(version, []):
                 for route_key in self._get_route_keys(route=route):
-                    active_routes.pop(route_key, None)
+                    active.pop(route_key, None)
+            result[version] = dict(active)
 
-            routes_by_version[version] = dict(active_routes)
+        return result
+
+    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(self._iter_routes_flat(router.routes))
 
-        return routes_by_version
+        return self._resolve_lifecycle(all_routes)
 
     def _get_webhooks_by_version(self) -> dict[VersionT, list[Any]]:
         if not self._webhook_routers:
@@ -354,32 +445,24 @@ class RouterVersioner:
 
         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
+            all_webhooks.extend(self._iter_routes_flat(router.routes))
+
+        return {version: list(routes.values()) for version, routes in self._resolve_lifecycle(all_webhooks).items()}
+
+    def _claim_prefix(self, prefix: str) -> None:
+        claimed: set[str] | None = getattr(self._app.state, "_router_versioner_claimed_prefixes", None)
+        if claimed is None:
+            claimed = set()
+            self._app.state._router_versioner_claimed_prefixes = claimed
+
+        if prefix in claimed:
+            raise RuntimeError(
+                f"Prefix '{prefix}' is already used by another RouterVersioner attached to this app. "
+                "Two RouterVersioner instances sharing the same app must use distinct "
+                "prefix_format/latest_prefix values, otherwise their docs/openapi routes silently "
+                "shadow each other."
+            )
+        claimed.add(prefix)
 
     def _resolve_webhooks_for_version(
         self, version: VersionT, webhooks_by_version: dict[VersionT, list[Any]]
@@ -395,19 +478,56 @@ class RouterVersioner:
             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)
+    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 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
+        if self._sort_routes:
+            routes_by_key = dict(sorted(routes_by_key.items()))
 
-        return routes_by_key
+        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 _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 = self._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 and self._version_gte(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)
 
     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)
@@ -563,94 +683,3 @@ class RouterVersioner:
                 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)
-
-    def _register_validation_exception_handler(self) -> None:
-        if getattr(self._app.state, "_validation_overridden", False):
-            return
-
-        @self._app.exception_handler(RequestValidationError)
-        async def custom_validation_exception_handler(_request: Request, exc: RequestValidationError) -> JSONResponse:
-            return JSONResponse(
-                status_code=self._validation_error_code,
-                content={"detail": jsonable_encoder(exc.errors())},
-            )
-
-        self._app.state._validation_overridden = True
-
-    def _patch_validation_error_openapi(self, schema: dict[str, Any]) -> None:
-        if self._validation_error_code == 422:
-            return
-
-        target_code = str(self._validation_error_code)
-        http_methods = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
-
-        for _path, path_item in schema.get("paths", {}).items():
-            for _method, operation in path_item.items():
-                if _method not in http_methods:
-                    continue
-
-                responses = operation.get("responses", {})
-                if "422" in responses:
-                    response_422 = responses["422"]
-                    content_422 = response_422.get("content", {}).get("application/json", {})
-                    schema_422 = content_422.get("schema", {})
-                    ref = schema_422.get("$ref", "")
-
-                    if ref.endswith("HTTPValidationError"):
-                        if target_code in responses:
-                            existing_response = responses[target_code]
-                            existing_content = existing_response.setdefault("content", {}).setdefault(
-                                "application/json", {}
-                            )
-                            existing_schema = existing_content.setdefault("schema", {})
-
-                            if "anyOf" in existing_schema:
-                                existing_schema["anyOf"].append(schema_422)
-                            elif existing_schema:
-                                existing_content["schema"] = {"anyOf": [existing_schema, schema_422]}
-                            else:
-                                existing_content["schema"] = schema_422
-
-                            old_desc = existing_response.get("description", "Error")
-                            existing_response["description"] = f"{old_desc} / Validation Error"
-
-                            del responses["422"]
-                        else:
-                            responses[target_code] = responses.pop("422")

{fastapi_router_versioning-0.2.1 → fastapi_router_versioning-0.2.2}/tests/test_versioner.py

@@ -218,6 +218,43 @@ def test_openapi_with_root_path_and_oauth2() -> None:
     assert schema["servers"][0]["url"] == "/api"
 
 
+def test_versioned_app_mounted_as_real_sub_application() -> None:
+    """A RouterVersioner-managed app works correctly when actually mounted via app.mount(),
+    not just simulated with a root_path passed to TestClient. Covers the ASGI root_path
+    FastAPI injects for real sub-applications: versioned docs/openapi, the root openapi patch
+    (validation_error_code), and runtime behavior must all resolve under the mount prefix."""
+    main_app = FastAPI()
+    sub_app = FastAPI()
+    router = APIRouter()
+
+    @router.post("/items")
+    @api_version((1, 0))
+    def create_item(count: int) -> dict[str, str]: ...
+
+    RouterVersioner(
+        app=sub_app, routers=router, version_format=VersionFormat.SEMVER, validation_error_code=400
+    ).versionize()
+
+    main_app.mount("/sub", sub_app)
+
+    client = TestClient(main_app)
+
+    # Sub-app's own root schema (accessed through the mount) reflects validation_error_code.
+    sub_root_schema = client.get("/sub/openapi.json").json()
+    operation = sub_root_schema["paths"]["/v1_0/items"]["post"]
+    assert "400" in operation["responses"]
+    assert "422" not in operation["responses"]
+    assert sub_root_schema["servers"][0]["url"] == "/sub"
+
+    # Versioned schema is consistent too.
+    versioned_schema = client.get("/sub/v1_0/openapi.json").json()
+    assert versioned_schema["servers"][0]["url"] == "/sub"
+
+    # Runtime resolves correctly through the mount, with the custom code applied.
+    assert client.post("/sub/v1_0/items?count=bad", json={}).status_code == 400
+    assert client.get("/sub/v1_0/docs").status_code == 200
+
+
 def test_custom_formats_coverage() -> None:
     """Custom prefix_format and semantic_version_format are applied correctly."""
     app = FastAPI()
@@ -1067,7 +1104,18 @@ def test_validation_error_handler_registered_once_for_multiple_versioners() -> N
     client = TestClient(app)
     assert client.get("/v1_0/a?count=bad").status_code == 400
     assert client.get("/v2_0/b?count=bad").status_code == 400
-    assert getattr(app.state, "_validation_overridden", False) is True
+    assert getattr(app.state, "_validation_effective_code", None) == 400
+
+
+def test_version_gte_mismatched_types_returns_false() -> None:
+    """_version_gte returns False for values that aren't both tuples or both strings.
+
+    Defensive branch: normally unreachable via the public API, since _validate_version_type
+    enforces a single, consistent VersionT type (tuple for SEMVER, str for CALVER) per
+    RouterVersioner instance.
+    """
+    assert RouterVersioner._version_gte((1, 0), "2025-01-01") is False
+    assert RouterVersioner._version_gte("2025-01-01", (1, 0)) is False
 
 
 def test_patch_validation_error_openapi_skips_non_method_keys() -> None:
@@ -1098,6 +1146,163 @@ def test_patch_validation_error_openapi_skips_non_method_keys() -> None:
     assert "parameters" in schema["paths"]["/items"]  # non-method key untouched
 
 
+def test_root_openapi_reflects_validation_error_code() -> None:
+    """The app's own /openapi.json (not versioned) also reflects validation_error_code."""
+    app = FastAPI()
+    router = APIRouter()
+
+    @router.get("/items")
+    @api_version((1, 0))
+    def get_items(count: int) -> dict[str, str]: ...
+
+    RouterVersioner(
+        app=app, routers=router, version_format=VersionFormat.SEMVER, validation_error_code=400
+    ).versionize()
+
+    client = TestClient(app)
+    root_schema = client.get("/openapi.json").json()
+    operation = root_schema["paths"]["/v1_0/items"]["get"]
+    assert "400" in operation["responses"]
+    assert "422" not in operation["responses"]
+    assert client.get("/v1_0/items?count=bad").status_code == 400
+
+
+def test_root_openapi_reflects_effective_code_for_default_versioner() -> None:
+    """A RouterVersioner left at the default 422 still shows the real app-wide code in the
+    root schema, when another RouterVersioner on the same app registered the actual handler."""
+    app = FastAPI()
+    router1 = APIRouter()
+    router2 = APIRouter()
+
+    @router1.get("/a")
+    @api_version((1, 0))
+    def route_a(count: int) -> dict[str, str]: ...
+
+    @router2.get("/b")
+    @api_version((2, 0))
+    def route_b(count: int) -> dict[str, str]: ...
+
+    RouterVersioner(
+        app=app, routers=router1, version_format=VersionFormat.SEMVER, validation_error_code=400
+    ).versionize()
+    RouterVersioner(app=app, routers=router2, version_format=VersionFormat.SEMVER).versionize()
+
+    client = TestClient(app)
+    root_schema = client.get("/openapi.json").json()
+    assert "400" in root_schema["paths"]["/v2_0/b"]["get"]["responses"]
+    assert "422" not in root_schema["paths"]["/v2_0/b"]["get"]["responses"]
+    assert client.get("/v2_0/b?count=bad").status_code == 400
+
+
+def test_versioned_schema_reflects_effective_code_for_default_versioner() -> None:
+    """A RouterVersioner left at the default 422 still shows the real app-wide code in its
+    own versioned schema when another RouterVersioner on the same app registered the actual
+    handler."""
+    app = FastAPI()
+    router1 = APIRouter()
+    router2 = APIRouter()
+
+    @router1.get("/a")
+    @api_version((1, 0))
+    def route_a(count: int) -> dict[str, str]: ...
+
+    @router2.get("/b")
+    @api_version((2, 0))
+    def route_b(count: int) -> dict[str, str]: ...
+
+    RouterVersioner(
+        app=app, routers=router1, version_format=VersionFormat.SEMVER, validation_error_code=400
+    ).versionize()
+    RouterVersioner(app=app, routers=router2, version_format=VersionFormat.SEMVER).versionize()
+
+    client = TestClient(app)
+    schema = client.get("/v2_0/openapi.json").json()
+    assert "400" in schema["paths"]["/v2_0/b"]["get"]["responses"]
+    assert "422" not in schema["paths"]["/v2_0/b"]["get"]["responses"]
+    assert client.get("/v2_0/b?count=bad").status_code == 400
+
+
+def test_conflicting_validation_error_codes_raise() -> None:
+    """Two RouterVersioners with different explicit validation_error_code and
+    handle_validation_exceptions=True must fail fast instead of silently ignoring the second."""
+    app = FastAPI()
+    router1 = APIRouter()
+    router2 = APIRouter()
+
+    RouterVersioner(app=app, routers=router1, version_format=VersionFormat.SEMVER, validation_error_code=400)
+
+    with pytest.raises(RuntimeError, match="conflicts with the requested"):
+        RouterVersioner(app=app, routers=router2, version_format=VersionFormat.SEMVER, validation_error_code=409)
+
+
+def test_handle_validation_exceptions_false_ignores_other_versioner_code() -> None:
+    """A versioner with handle_validation_exceptions=False always shows its own requested
+    code in its schema, regardless of what other versioners on the same app registered."""
+    app = FastAPI()
+    router1 = APIRouter()
+    router2 = APIRouter()
+
+    @router2.get("/items")
+    @api_version((1, 0))
+    def get_items(count: int) -> dict[str, str]: ...
+
+    RouterVersioner(app=app, routers=router1, version_format=VersionFormat.SEMVER, validation_error_code=400)
+    RouterVersioner(
+        app=app,
+        routers=router2,
+        version_format=VersionFormat.SEMVER,
+        validation_error_code=409,
+        handle_validation_exceptions=False,
+    ).versionize()
+
+    client = TestClient(app)
+    schema = client.get("/v1_0/openapi.json").json()
+    assert "409" in schema["paths"]["/v1_0/items"]["get"]["responses"]
+
+
+def test_duplicate_version_prefix_across_versioners_raises() -> None:
+    """Two RouterVersioners producing the same version prefix on the same app must fail fast
+    instead of silently shadowing each other's docs/openapi routes."""
+    app = FastAPI()
+    router1 = APIRouter()
+    router2 = APIRouter()
+
+    @router1.get("/a")
+    @api_version((1, 0))
+    def route_a() -> dict[str, str]: ...
+
+    @router2.get("/b")
+    @api_version((1, 0))
+    def route_b() -> dict[str, str]: ...
+
+    RouterVersioner(app=app, routers=router1, version_format=VersionFormat.SEMVER).versionize()
+
+    with pytest.raises(RuntimeError, match="already used by another RouterVersioner"):
+        RouterVersioner(app=app, routers=router2, version_format=VersionFormat.SEMVER).versionize()
+
+
+def test_duplicate_latest_prefix_across_versioners_raises() -> None:
+    """Two RouterVersioners sharing the same latest_prefix on the same app must fail fast."""
+    app = FastAPI()
+    router1 = APIRouter()
+    router2 = APIRouter()
+
+    @router1.get("/a")
+    @api_version((1, 0))
+    def route_a() -> dict[str, str]: ...
+
+    @router2.get("/b")
+    @api_version("2025-01-01")
+    def route_b() -> dict[str, str]: ...
+
+    RouterVersioner(app=app, routers=router1, version_format=VersionFormat.SEMVER, latest_prefix="/latest").versionize()
+
+    with pytest.raises(RuntimeError, match="already used by another RouterVersioner"):
+        RouterVersioner(
+            app=app, routers=router2, version_format=VersionFormat.CALVER, latest_prefix="/latest"
+        ).versionize()
+
+
 def test_iter_routes_flat_fallback_without_route_context_fn() -> None:
     """Covers the _route_contexts_fn=None fallback (legacy FastAPI < 0.137.2).
 
@@ -1115,7 +1320,7 @@ def test_iter_routes_flat_fallback_without_route_context_fn() -> None:
     original_fn = versioner_module._route_contexts_fn
     try:
         versioner_module._route_contexts_fn = None
-        result = list(versioner_module._iter_routes_flat(router.routes))
+        result = list(versioner_module.RouterVersioner._iter_routes_flat(router.routes))
         assert result == list(router.routes)
     finally:
         versioner_module._route_contexts_fn = original_fn