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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-router-versioning
-Version: 0.2.0
+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.0 → 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.0 → fastapi_router_versioning-0.2.2}/RELEASE_NOTES.md

@@ -2,6 +2,27 @@
 
 ## 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
+
+* 🐛 Fix `api_version` signature to enforce `deprecate_in` and `remove_in` as keyword-only arguments, aligning the implementation with the documented signature. PR [#18](https://github.com/mat81black/fastapi-router-versioning/pull/18) by [@mat81black](https://github.com/mat81black).
+
 ## 0.2.0 (2026-06-26)
 
 ### Features

{fastapi_router_versioning-0.2.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0"
+__version__ = "0.2.2"
 
 __all__ = ["RouterVersioner", "api_version", "VersionFormat", "VersionT"]