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

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/.github/workflows/pre-commit.yml

@@ -21,7 +21,7 @@ jobs:
         run: echo "$GITHUB_CONTEXT"
 
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
           # Full history required for --from-ref/--to-ref diff in prek

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/.github/workflows/prepare-release.yml

@@ -31,7 +31,7 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: true
       - name: Set up Python

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/.github/workflows/publish.yml

@@ -20,7 +20,7 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - name: Set up Python

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/.github/workflows/test-redistribute.yml

@@ -20,7 +20,7 @@ jobs:
     outputs:
       src: ${{ steps.filter.outputs.src }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
@@ -48,7 +48,7 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - name: Set up Python

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/.github/workflows/test.yml

@@ -25,7 +25,7 @@ jobs:
     outputs:
       src: ${{ steps.filter.outputs.src }}
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
@@ -70,7 +70,7 @@ jobs:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
@@ -122,7 +122,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: fastapi-router-versioning
-Version: 0.1.1
-Summary: Native, router-based API versioning for FastAPI, featuring per-version docs and a declarative route lifecycle.
+Version: 0.2.0
+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
 Project-URL: Issues, https://github.com/mat81black/fastapi-router-versioning/issues
@@ -19,6 +19,7 @@ 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -26,15 +27,15 @@ 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)
+# FastAPI Router 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**.
+Router-based API versioning for 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.
+FastAPI has no built-in versioning mechanism. The common workaround — duplicating routers or managing prefixes manually — breaks down quickly as the number of versions grows. This package adds declarative versioning directly on routes, with isolated URL prefixes, per-version Swagger UI, and a full route lifecycle, without touching the existing application structure.
 
 ---
 
@@ -46,6 +47,7 @@ If you want to implement **FastAPI API versioning**, you can simply annotate you
 - **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
+- **Configurable validation error code** — return `400` (or any code) instead of `422` for request validation errors, with the OpenAPI schema updated automatically
 - **Broad compatibility** — works with nested routers, WebSockets, `Depends`, and OpenAPI Callbacks
 
 ---
@@ -93,7 +95,7 @@ RouterVersioner(app=app, routers=router, version_format=VersionFormat.SEMVER).ve
 # 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.
+Each version gets its own Swagger UI at `/v1_0/docs`, `/v2_0/docs`, and so on.
 
 ---
 
@@ -117,9 +119,9 @@ RouterVersioner(app=app, routers=router, version_format=VersionFormat.CALVER).ve
 # Mounts: GET /2025-01-01/items
 ```
 
-Any string is a valid CalVer token: `"2025-01-01"`, `"v3"`, `"stable"`, etc.
+Valid CalVer tokens: `"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.
+**CalVer sorting:** versions are sorted lexicographically, so tokens must be comparable in the intended order. ISO dates (`"2025-01-01"`) and zero-padded numbers (`"v01"`, `"v02"`) work correctly. Non-padded strings like `"v1"`, `"v10"`, `"v2"` will not sort correctly and will cause routes to appear in the wrong versions.
 
 ---
 
@@ -168,6 +170,8 @@ Routes without `@api_version` fall back to `default_version` (default: `(1, 0)`
 | `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 |
+| `validation_error_code` | `int` | `422` | HTTP status code returned for request validation errors; also replaces the `422` entry in the OpenAPI schema |
+| `handle_validation_exceptions` | `bool` | `True` | If `False`, only the schema is updated — register your own `RequestValidationError` handler to control the response body |
 
 Call `.versionize()` after constructing the object. It returns the list of active versions.
 
@@ -181,8 +185,8 @@ Call `.versionize()` after constructing the object. It returns the list of activ
 
 | 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 |
+| `version` | `tuple[int, int] \| str` | yes | First version in which this route is active |
+| `deprecate_in` | same \| `None` | no | Version in which 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`
@@ -278,7 +282,7 @@ RouterVersioner(
 ).versionize()
 ```
 
-The hook receives `(schema: dict, version: VersionT)` and must return the (modified) dict.
+The hook receives `(schema: dict, version: VersionT)` and must return the modified dict.
 
 ### OpenAPI Callbacks and Webhooks
 
@@ -325,12 +329,11 @@ RouterVersioner(
 # /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.
+The same `remove_in` lifecycle applies. 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:
+Pass a list of routers to version routes split across modules:
 
 ```python
 RouterVersioner(
@@ -344,7 +347,7 @@ 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:
+By default, Swagger UI and ReDoc assets are loaded from the FastAPI CDN. In air-gapped or corporate environments, point them at locally hosted assets:
 
 ```python
 RouterVersioner(
@@ -360,7 +363,42 @@ RouterVersioner(
 ).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.
+See [`examples/download_static_assets.py`](examples/download_static_assets.py) for a 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.
+
+### Validation error code
+
+By default FastAPI returns `422 Unprocessable Entity` for request validation errors.
+Use `validation_error_code` to change the code returned both at runtime and in the OpenAPI schema:
+
+```python
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    validation_error_code=400,
+).versionize()
+# Validation errors now return 400; the schema shows 400 instead of 422
+```
+
+To keep full control over the response body, set `handle_validation_exceptions=False` and register your own handler:
+
+```python
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(RequestValidationError)
+async def my_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    return JSONResponse(status_code=400, content={"errors": exc.errors()})
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    validation_error_code=400,
+    handle_validation_exceptions=False,  # schema updated; handler is yours
+).versionize()
+```
 
 ### Reverse proxy / sub-app mounting
 
@@ -402,6 +440,8 @@ Runnable examples are available in the [`examples/`](examples/) directory:
 | [`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 |
+| [`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 |
 
 ---
 

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/README.md

@@ -1,12 +1,12 @@
-# FastAPI Router Versioning (Native API Versioning)
+# FastAPI Router 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**.
+Router-based API versioning for 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.
+FastAPI has no built-in versioning mechanism. The common workaround — duplicating routers or managing prefixes manually — breaks down quickly as the number of versions grows. This package adds declarative versioning directly on routes, with isolated URL prefixes, per-version Swagger UI, and a full route lifecycle, without touching the existing application structure.
 
 ---
 
@@ -18,6 +18,7 @@ If you want to implement **FastAPI API versioning**, you can simply annotate you
 - **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
+- **Configurable validation error code** — return `400` (or any code) instead of `422` for request validation errors, with the OpenAPI schema updated automatically
 - **Broad compatibility** — works with nested routers, WebSockets, `Depends`, and OpenAPI Callbacks
 
 ---
@@ -65,7 +66,7 @@ RouterVersioner(app=app, routers=router, version_format=VersionFormat.SEMVER).ve
 # 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.
+Each version gets its own Swagger UI at `/v1_0/docs`, `/v2_0/docs`, and so on.
 
 ---
 
@@ -89,9 +90,9 @@ RouterVersioner(app=app, routers=router, version_format=VersionFormat.CALVER).ve
 # Mounts: GET /2025-01-01/items
 ```
 
-Any string is a valid CalVer token: `"2025-01-01"`, `"v3"`, `"stable"`, etc.
+Valid CalVer tokens: `"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.
+**CalVer sorting:** versions are sorted lexicographically, so tokens must be comparable in the intended order. ISO dates (`"2025-01-01"`) and zero-padded numbers (`"v01"`, `"v02"`) work correctly. Non-padded strings like `"v1"`, `"v10"`, `"v2"` will not sort correctly and will cause routes to appear in the wrong versions.
 
 ---
 
@@ -140,6 +141,8 @@ Routes without `@api_version` fall back to `default_version` (default: `(1, 0)`
 | `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 |
+| `validation_error_code` | `int` | `422` | HTTP status code returned for request validation errors; also replaces the `422` entry in the OpenAPI schema |
+| `handle_validation_exceptions` | `bool` | `True` | If `False`, only the schema is updated — register your own `RequestValidationError` handler to control the response body |
 
 Call `.versionize()` after constructing the object. It returns the list of active versions.
 
@@ -153,8 +156,8 @@ Call `.versionize()` after constructing the object. It returns the list of activ
 
 | 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 |
+| `version` | `tuple[int, int] \| str` | yes | First version in which this route is active |
+| `deprecate_in` | same \| `None` | no | Version in which 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`
@@ -250,7 +253,7 @@ RouterVersioner(
 ).versionize()
 ```
 
-The hook receives `(schema: dict, version: VersionT)` and must return the (modified) dict.
+The hook receives `(schema: dict, version: VersionT)` and must return the modified dict.
 
 ### OpenAPI Callbacks and Webhooks
 
@@ -297,12 +300,11 @@ RouterVersioner(
 # /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.
+The same `remove_in` lifecycle applies. 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:
+Pass a list of routers to version routes split across modules:
 
 ```python
 RouterVersioner(
@@ -316,7 +318,7 @@ 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:
+By default, Swagger UI and ReDoc assets are loaded from the FastAPI CDN. In air-gapped or corporate environments, point them at locally hosted assets:
 
 ```python
 RouterVersioner(
@@ -332,7 +334,42 @@ RouterVersioner(
 ).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.
+See [`examples/download_static_assets.py`](examples/download_static_assets.py) for a 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.
+
+### Validation error code
+
+By default FastAPI returns `422 Unprocessable Entity` for request validation errors.
+Use `validation_error_code` to change the code returned both at runtime and in the OpenAPI schema:
+
+```python
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    validation_error_code=400,
+).versionize()
+# Validation errors now return 400; the schema shows 400 instead of 422
+```
+
+To keep full control over the response body, set `handle_validation_exceptions=False` and register your own handler:
+
+```python
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(RequestValidationError)
+async def my_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    return JSONResponse(status_code=400, content={"errors": exc.errors()})
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    validation_error_code=400,
+    handle_validation_exceptions=False,  # schema updated; handler is yours
+).versionize()
+```
 
 ### Reverse proxy / sub-app mounting
 
@@ -374,6 +411,8 @@ Runnable examples are available in the [`examples/`](examples/) directory:
 | [`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 |
+| [`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 |
 
 ---
 

fastapi_router_versioning-0.2.0/RELEASE_NOTES.md

@@ -0,0 +1,58 @@
+# Release Notes
+
+## Latest Changes
+
+## 0.2.0 (2026-06-26)
+
+### Features
+
+* ✨ Add `validation_error_code` parameter to `RouterVersioner` to override the HTTP status code returned for request validation errors (default: `422`). The OpenAPI schema is updated automatically to reflect the custom code. PR [#16](https://github.com/mat81black/fastapi-router-versioning/pull/16) by [@mat81black](https://github.com/mat81black).
+* ✨ Add `handle_validation_exceptions` parameter to `RouterVersioner`: when `False`, only the OpenAPI schema is updated, leaving the exception handler to the user. PR [#16](https://github.com/mat81black/fastapi-router-versioning/pull/16) by [@mat81black](https://github.com/mat81black).
+
+### Fixes
+
+* 🐛 Fix Python 3.14 classifier not actually added to `pyproject.toml` in 0.1.2. PR [#15](https://github.com/mat81black/fastapi-router-versioning/pull/15) by [@mat81black](https://github.com/mat81black).
+
+## 0.1.2 (2026-06-25)
+
+### Internal
+
+* 👷 Add Python 3.14 classifier to `pyproject.toml` to align with the versions already covered by CI.
+
+### Docs
+
+* 📝 Update README and `pyproject.toml` to clarify package description and improve documentation consistency. PR [#12](https://github.com/mat81black/fastapi-router-versioning/pull/12) by [@mat81black](https://github.com/mat81black).
+
+## 0.1.1 (2026-06-24)
+
+### Features
+
+* ✨ Add per-version OpenAPI schema caching: schemas are generated once and cached, reducing overhead on repeated requests. PR [#5](https://github.com/mat81black/fastapi-router-versioning/pull/5) by [@mat81black](https://github.com/mat81black).
+* ✨ Track which routes belong to each version to invalidate the cache automatically when the route set changes. PR [#5](https://github.com/mat81black/fastapi-router-versioning/pull/5) by [@mat81black](https://github.com/mat81black).
+
+### Fixes
+
+* 🐛 Fix WebSocket routes not being handled correctly in `versioned_routers` when the cache was active. PR [#5](https://github.com/mat81black/fastapi-router-versioning/pull/5) by [@mat81black](https://github.com/mat81black).
+* 🐛 Improve OpenAPI schema cache resilience: cache is now safely bypassed on unexpected errors instead of raising. PR [#5](https://github.com/mat81black/fastapi-router-versioning/pull/5) by [@mat81black](https://github.com/mat81black).
+
+### Internal
+
+* 👷 Add `prepare-release.yml` workflow and `scripts/prepare_release.py` for automated version bumping and release PR creation. PR [#6](https://github.com/mat81black/fastapi-router-versioning/pull/6) by [@mat81black](https://github.com/mat81black).
+* 👷 Add `changes` job to `test.yml` and `test-redistribute.yml` to skip CI when no relevant files are modified. PR [#10](https://github.com/mat81black/fastapi-router-versioning/pull/10) by [@mat81black](https://github.com/mat81black).
+
+## 0.1.0 (2025-06-24)
+
+🚀 First official public release of **fastapi-router-versioning**.
+
+Router-based API versioning for FastAPI, with declarative route lifecycle, per-version OpenAPI schemas, and isolated documentation — without altering the core application structure.
+
+### Features
+
+* ✨ SemVer & CalVer support: route versioning using `(major, minor)` tuples or lexicographically sortable arbitrary strings.
+* ✨ Declarative route lifecycle: introduce, deprecate (`deprecate_in`), and remove (`remove_in`) routes across versions.
+* ✨ Per-version documentation: isolated Swagger UI, ReDoc, and `openapi.json` for each active version.
+* ✨ OpenAPI schema hook: modify the filtered schema per version via `openapi_hook`.
+* ✨ Independent webhook versioning via `webhook_routers`, with propagation of per-route OpenAPI Callbacks.
+* ✨ Latest-version alias: expose the highest active version under a stable configurable prefix.
+* ✨ Self-hosted docs: full control over Swagger/ReDoc static assets and option to disable Google Fonts.
+* ✨ Reverse proxy aware: resolves and injects the ASGI `root_path` at request time.

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/examples/openapi_hook_app.py

@@ -58,4 +58,4 @@ versioner.versionize()
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(app, host="127.0.0.1", port=8003)
+    uvicorn.run(app, host="127.0.0.1", port=8004)

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/examples/self_hosted_docs_app.py

@@ -54,4 +54,4 @@ versioner.versionize()
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(app, host="127.0.0.1", port=8004)
+    uvicorn.run(app, host="127.0.0.1", port=8005)

fastapi_router_versioning-0.2.0/examples/validation_error_code_app.py

@@ -0,0 +1,57 @@
+"""Demonstrate overriding the HTTP status code returned for request validation errors.
+
+By default FastAPI returns 422 Unprocessable Entity for validation errors.
+``validation_error_code=400`` makes RouterVersioner register an exception handler
+and update the OpenAPI schema to reflect the custom code automatically.
+
+Run:
+    python examples/validation_error_code_app.py
+
+Then open http://127.0.0.1:8007/v1_0/docs and try ``POST /v1_0/items`` with body
+``{"name": "widget", "quantity": "not-a-number"}`` to see the 400 response from
+the server (not a Swagger client-side message).
+"""
+
+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
+
+
+app = FastAPI(
+    title="Validation Error Code — Automatic Handler",
+    description=(
+        "Validation errors return **400 Bad Request** instead of 422.\n\n"
+        'Try `POST /v1_0/items` with body `{"name": "widget", "quantity": "not-a-number"}` '
+        "to see the 400 response from the server."
+    ),
+)
+
+router = APIRouter()
+
+
+@router.post("/items")
+@api_version((1, 0))
+def create_item(body: CreateItemRequest) -> dict[str, str]:
+    """Create an item. ``name`` must be a string, ``quantity`` must be an integer."""
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    validation_error_code=400,
+    # handle_validation_exceptions=True is the default: no extra code needed.
+).versionize()
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=8007)

fastapi_router_versioning-0.2.0/examples/validation_error_code_custom_handler_app.py

@@ -0,0 +1,70 @@
+"""Demonstrate using a custom validation exception handler alongside validation_error_code.
+
+Setting ``handle_validation_exceptions=False`` tells RouterVersioner to update the
+OpenAPI schema (so it shows 400 instead of 422) without registering any handler.
+You then register your own handler for full control over the response body.
+
+Run:
+    python examples/validation_error_code_custom_handler_app.py
+
+Then open http://127.0.0.1:8008/v1_0/docs and try ``POST /v1_0/orders`` with body
+``{"name": "widget", "quantity": "not-a-number"}`` to see the custom 400 response
+with field-level error messages.
+"""
+
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
+
+
+class CreateOrderRequest(BaseModel):
+    name: str
+    quantity: int
+
+
+app = FastAPI(
+    title="Validation Error Code — Custom Handler",
+    description=(
+        "Validation errors return **400 Bad Request** with a custom response body.\n\n"
+        'Try `POST /v1_0/orders` with body `{"name": "widget", "quantity": "not-a-number"}` '
+        "to see the custom handler response."
+    ),
+)
+
+router = APIRouter()
+
+
+@router.post("/orders")
+@api_version((1, 0))
+def create_order(body: CreateOrderRequest) -> dict[str, str]:
+    """Create an order. ``name`` must be a string, ``quantity`` must be an integer."""
+    return {"name": body.name, "quantity": str(body.quantity)}
+
+
+@app.exception_handler(RequestValidationError)
+async def my_validation_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    """Returns field-level error messages under an 'errors' key."""
+    return JSONResponse(
+        status_code=400,
+        content={
+            "errors": [{"field": e["loc"][-1], "message": e["msg"]} for e in exc.errors()],
+        },
+    )
+
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    validation_error_code=400,
+    handle_validation_exceptions=False,  # OpenAPI schema shows 400; handler is yours.
+).versionize()
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=8008)

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/examples/webhook_versioning_app.py

@@ -88,4 +88,4 @@ versioner.versionize()
 if __name__ == "__main__":
     import uvicorn
 
-    uvicorn.run(app, host="127.0.0.1", port=8004)
+    uvicorn.run(app, host="127.0.0.1", port=8006)

{fastapi_router_versioning-0.1.1 → fastapi_router_versioning-0.2.0}/fastapi_router_versioning/__init__.py

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