fastapi-router-versioning 0.2.6__tar.gz → 0.3.0__tar.gz

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/dependabot.yml

@@ -4,7 +4,7 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "monthly"
     cooldown:
       default-days: 7
     commit-message:
@@ -21,7 +21,7 @@ updates:
   - package-ecosystem: "uv"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "monthly"
     cooldown:
       default-days: 7
     commit-message:
@@ -31,20 +31,3 @@ updates:
         dependency-type: "development"
         patterns:
           - "*"
-  # pre-commit
-  - package-ecosystem: "pre-commit"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    cooldown:
-      default-days: 7
-    commit-message:
-      prefix: ⬆
-    labels:
-      - "internal"
-      - "dependencies"
-      - "pre-commit"
-    groups:
-      pre-commit:
-        patterns:
-          - "*"

fastapi_router_versioning-0.3.0/.github/workflows/bump-pre-commit-hooks.yml

@@ -0,0 +1,67 @@
+name: Bump pre-commit hooks
+
+on:
+  schedule:
+    - cron: "0 12 1 * *"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  bump-pre-commit-hooks:
+    if: github.repository_owner == 'mat81black'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          token: ${{ secrets.FASTAPI_ROUTER_VERSIONING_LATEST_CHANGES }}
+          persist-credentials: true
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: ".python-version"
+      - name: Setup uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
+          # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837
+          version: "0.11.18"
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+      - name: Bump pre-commit hooks
+        run: uv run prek auto-update --freeze --cooldown-days 7
+      - name: Create pull request
+        env:
+          GH_TOKEN: ${{ secrets.FASTAPI_ROUTER_VERSIONING_LATEST_CHANGES }}
+          BASE_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          if git diff --quiet; then
+            echo "No pre-commit hook updates available"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          branch="bump-pre-commit-hooks"
+          git switch -C "$branch"
+          git add .pre-commit-config.yaml
+          git commit -m "⬆ Bump pre-commit hooks"
+          git push --force origin "$branch"
+          if [ -z "$(gh pr list --head "$branch" --state open --json number --jq '.[].number')" ]; then
+            gh pr create \
+              --base "$BASE_BRANCH" \
+              --head "$branch" \
+              --title "⬆ Bump pre-commit hooks" \
+              --body "Bump pre-commit hook versions via \`prek auto-update --freeze --cooldown-days 7\`." \
+              --label internal \
+              --label dependencies \
+              --label pre-commit
+          else
+            echo "PR for \"$branch\" already open; branch updated in place."
+          fi

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/create-draft-release.yml

@@ -22,16 +22,16 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.repository.default_branch }}
           persist-credentials: true
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version-file: ".python-version"
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
           # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/labeler.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-    - uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213 # v6.1.0
+    - uses: actions/labeler@bf12e9b00b37c5c0ca2b87b79b2daf7891dbda13 # v7.0.0
       if: ${{ github.event.action != 'labeled' && github.event.action != 'unlabeled' }}
     - run: echo "Done adding labels"
   # Run this after labeler applied labels

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/latest-changes.yml

@@ -28,7 +28,7 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.repository.default_branch }}
           # To allow latest-changes to commit to the main branch

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/pre-commit.yml

@@ -18,19 +18,19 @@ jobs:
         run: echo "$GITHUB_CONTEXT"
 
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
           # Full history required for --from-ref/--to-ref diff in prek
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version-file: ".python-version"
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
           # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/prepare-release.yml

@@ -34,16 +34,16 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           token: ${{ secrets.FASTAPI_ROUTER_VERSIONING_LATEST_CHANGES }} # zizmor: ignore[secrets-outside-env]
           persist-credentials: true
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version-file: ".python-version"
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
           # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/publish.yml

@@ -20,15 +20,15 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version-file: ".python-version"
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
           # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/test-redistribute.yml

@@ -18,7 +18,7 @@ jobs:
     outputs:
       src: ${{ steps.filter.outputs.src }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
@@ -46,11 +46,11 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version-file: ".python-version"
       - name: Install build dependencies

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/test.yml

@@ -26,7 +26,7 @@ jobs:
     outputs:
       src: ${{ steps.filter.outputs.src }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       # For pull requests it's not necessary to checkout the code but for the main branch it is
@@ -72,17 +72,17 @@ jobs:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
           # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837
@@ -130,12 +130,12 @@ jobs:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           # Before upgrading uv version, make sure astral-sh/setup-uv knows its checksum.
           # See: https://github.com/astral-sh/setup-uv/issues/851#issuecomment-4282017837

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.github/workflows/zizmor.yml

@@ -18,8 +18,8 @@ jobs:
       security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files.
     steps:
       - name: Checkout repository
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7
+        uses: zizmorcore/zizmor-action@6599ee8b7a49aef6a770f63d261d214911a7ce02 # v0.6.0

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/crate-ci/typos
-    rev: b859c0df7f391deba73030f79b957e62b4d81dc6 # varcon-core-v5.0.7
+    rev: bee27e3a4fd1ea2111cf90ab89cd076c870fce14 # frozen: v1.48.0
     hooks:
       - id: typos
         args: [ --force-exclude ]

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-router-versioning
-Version: 0.2.6
+Version: 0.3.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
@@ -49,7 +49,6 @@ Running multiple API versions side by side usually means duplicating routers, ha
 - **Latest alias**: expose the newest version under a fixed `/latest` prefix clients can pin to
 - **Self-hosted docs assets**: point Swagger UI and ReDoc at your own JS/CSS for air-gapped deployments
 - **Reverse proxy and sub-app aware**: doc URLs pick up the ASGI `root_path` at request time
-- **Configurable validation error status**: swap FastAPI's default `422` for any code, applied consistently to runtime responses and every OpenAPI schema, including the app's own root schema
 - **Route composition support**: works across nested routers, WebSockets, `Depends`, and OpenAPI Callbacks
 
 ---
@@ -154,6 +153,15 @@ def legacy_route():
 A route without `@api_version` isn't excluded, it falls back to `default_version`
 (`(1, 0)` for SemVer, `"1"` for CalVer, unless overridden).
 
+FastAPI's own `deprecated=True` (set directly on a route, or inherited from
+`APIRouter(deprecated=True)`) is preserved as-is: `RouterVersioner` copies it into every
+version unconditionally, on top of whatever `deprecate_in` computes. `deprecate_in` only
+ever turns deprecation *on* for versions at or after its boundary, it never turns off a
+`deprecated=True` that was already set natively. If you set both on the same route, it
+shows as deprecated in every version, including ones before `deprecate_in`'s boundary.
+Use one or the other: `deprecated=True` for an unconditional, version-independent flag,
+`deprecate_in` for a per-version lifecycle.
+
 ---
 
 ## `RouterVersioner` reference
@@ -180,8 +188,6 @@ A route without `@api_version` isn't excluded, it falls back to `default_version
 | `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` | Set `False` to stop ReDoc from loading Google Fonts |
-| `validation_error_code` | `int` | `422` | Status code returned for request validation errors; also replaces the `422` entry everywhere it appears in the OpenAPI schema, root schema included |
-| `handle_validation_exceptions` | `bool` | `True` | Set `False` to only patch the schema and register your own `RequestValidationError` handler |
 
 `.versionize()` returns the list of versions it activated. It can only be called once per
 instance; a second call raises `RuntimeError`, since it mutates the live FastAPI app in a way
@@ -290,6 +296,41 @@ RouterVersioner(
 ).versionize()
 ```
 
+### Custom validation error status code
+
+Changing FastAPI's default `422` for request validation errors is not something
+`RouterVersioner` does itself: it's a separate, general-purpose concern, handled by the
+[fastapi-validation-override](https://pypi.org/project/fastapi-validation-override/) package.
+`openapi_hook` is the integration point: it lets you re-apply the same patch to every
+per-version schema that `RouterVersioner` generates, so all of them, root schema included,
+stay consistent.
+
+```bash
+uv add fastapi-validation-override
+```
+
+```python
+from fastapi_validation_override import override_validation_error, patch_422_responses
+
+# 1. Registers the runtime handler and patches the app's own root /openapi.json.
+override_validation_error(app, status_code=400)
+
+# 2. Re-applies the same patch to each version's own schema.
+def versioning_openapi_hook(schema: dict, version: tuple[int, int]) -> dict:
+    return patch_422_responses(schema, "400")
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    openapi_hook=versioning_openapi_hook,
+).versionize()
+# Validation failures now return 400, both at runtime and in every schema
+# (root, and every /vX_Y/openapi.json)
+```
+
+See [`examples/validation_override_integration_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_override_integration_app.py).
+
 ### OpenAPI Callbacks and Webhooks
 
 Route-level **Callbacks** need no special handling: a `callbacks=[...]` argument on a route
@@ -373,63 +414,18 @@ RouterVersioner(
 [`examples/download_static_assets.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/download_static_assets.py) downloads the required files in one step;
 [`examples/self_hosted_docs_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/self_hosted_docs_app.py) wires them into a full app.
 
-### Validation error status code
-
-`validation_error_code` changes what FastAPI returns for a failed request body/query/path
-validation, `422` by default, both at runtime and in the schema:
-
-```python
-RouterVersioner(
-    app=app,
-    routers=router,
-    version_format=VersionFormat.SEMVER,
-    validation_error_code=400,
-).versionize()
-# Validation failures now return 400; every 422 entry in the schema becomes 400
-```
-
-Set `handle_validation_exceptions=False` to keep the schema change while writing your own
-response body:
-
-```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; the handler above owns the response
-).versionize()
-```
-
-This also patches the app's own root `/docs`, `/redoc`, and `/openapi.json`, not just the
-versioned ones, so there's nothing left showing the stale `422`.
-
 Sharing one app across several `RouterVersioner` instances only makes sense for one reason:
 mixing `version_format` values, SemVer for one group of routes and CalVer for another, on
 the same app. Splitting modules that share a `version_format` doesn't need a second instance;
 pass them all to one `RouterVersioner` via `routers=[...]` instead (see
 [`multi_router_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/multi_router_app.py)).
-If you do share an app across instances, two rules are enforced for you:
-
-- Every instance with `handle_validation_exceptions=True` must agree on
-  `validation_error_code`. FastAPI's exception handler is registered once per app, not per
-  router, so a mismatch raises `RuntimeError` when the second instance is constructed rather
-  than silently keeping whichever handler was registered first.
-- Every instance needs its own `prefix_format`/`latest_prefix`. Two instances that resolve to
-  the same prefix would otherwise overwrite each other's docs/openapi routes at the same
-  path; this raises `RuntimeError` too.
+If you do share an app across instances, one rule is enforced for you: every instance needs
+its own `prefix_format`/`latest_prefix`. Two instances that resolve to the same prefix would
+otherwise overwrite each other's docs/openapi routes at the same path; this raises
+`RuntimeError`.
 
-For modules that genuinely don't need to coordinate at all, including a different
-`validation_error_code` each, mount them as separate FastAPI sub-applications instead (next
-section).
+For modules that genuinely don't need to coordinate at all, mount them as separate FastAPI
+sub-applications instead (next section).
 
 ### Reverse proxy and sub-application mounting
 
@@ -444,7 +440,7 @@ parent.mount("/api", app)  # root_path="/api" is injected per request
 
 A mounted sub-application is a separate `FastAPI()` instance with its own `app.state`, so a
 `RouterVersioner` attached to it is entirely independent from one attached to the parent, or
-to another sub-application, no shared `validation_error_code`, no prefix coordination needed.
+to another sub-application, no prefix coordination needed.
 See [`examples/mounted_subapps_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/mounted_subapps_app.py).
 
 ### Callback hook
@@ -477,9 +473,8 @@ RouterVersioner(
 | [`multi_router_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/multi_router_app.py) | Several routers versioned together under one instance |
 | [`self_hosted_docs_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/self_hosted_docs_app.py) | Swagger UI and ReDoc served from local static assets |
 | [`openapi_hook_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/openapi_hook_app.py) | Per-version OpenAPI schema edits via `openapi_hook` |
-| [`validation_error_code_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_error_code_app.py) | `400` instead of `422`, handled automatically by `RouterVersioner` |
-| [`validation_error_code_custom_handler_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_error_code_custom_handler_app.py) | Same, but with `handle_validation_exceptions=False` and a custom handler |
 | [`mounted_subapps_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/mounted_subapps_app.py) | Independently versioned modules as separate `app.mount()` sub-applications |
+| [`validation_override_integration_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_override_integration_app.py) | Custom validation error status code via `fastapi-validation-override` and `openapi_hook` |
 
 ---
 

{fastapi_router_versioning-0.2.6 → fastapi_router_versioning-0.3.0}/README.md

@@ -18,7 +18,6 @@ Running multiple API versions side by side usually means duplicating routers, ha
 - **Latest alias**: expose the newest version under a fixed `/latest` prefix clients can pin to
 - **Self-hosted docs assets**: point Swagger UI and ReDoc at your own JS/CSS for air-gapped deployments
 - **Reverse proxy and sub-app aware**: doc URLs pick up the ASGI `root_path` at request time
-- **Configurable validation error status**: swap FastAPI's default `422` for any code, applied consistently to runtime responses and every OpenAPI schema, including the app's own root schema
 - **Route composition support**: works across nested routers, WebSockets, `Depends`, and OpenAPI Callbacks
 
 ---
@@ -123,6 +122,15 @@ def legacy_route():
 A route without `@api_version` isn't excluded, it falls back to `default_version`
 (`(1, 0)` for SemVer, `"1"` for CalVer, unless overridden).
 
+FastAPI's own `deprecated=True` (set directly on a route, or inherited from
+`APIRouter(deprecated=True)`) is preserved as-is: `RouterVersioner` copies it into every
+version unconditionally, on top of whatever `deprecate_in` computes. `deprecate_in` only
+ever turns deprecation *on* for versions at or after its boundary, it never turns off a
+`deprecated=True` that was already set natively. If you set both on the same route, it
+shows as deprecated in every version, including ones before `deprecate_in`'s boundary.
+Use one or the other: `deprecated=True` for an unconditional, version-independent flag,
+`deprecate_in` for a per-version lifecycle.
+
 ---
 
 ## `RouterVersioner` reference
@@ -149,8 +157,6 @@ A route without `@api_version` isn't excluded, it falls back to `default_version
 | `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` | Set `False` to stop ReDoc from loading Google Fonts |
-| `validation_error_code` | `int` | `422` | Status code returned for request validation errors; also replaces the `422` entry everywhere it appears in the OpenAPI schema, root schema included |
-| `handle_validation_exceptions` | `bool` | `True` | Set `False` to only patch the schema and register your own `RequestValidationError` handler |
 
 `.versionize()` returns the list of versions it activated. It can only be called once per
 instance; a second call raises `RuntimeError`, since it mutates the live FastAPI app in a way
@@ -259,6 +265,41 @@ RouterVersioner(
 ).versionize()
 ```
 
+### Custom validation error status code
+
+Changing FastAPI's default `422` for request validation errors is not something
+`RouterVersioner` does itself: it's a separate, general-purpose concern, handled by the
+[fastapi-validation-override](https://pypi.org/project/fastapi-validation-override/) package.
+`openapi_hook` is the integration point: it lets you re-apply the same patch to every
+per-version schema that `RouterVersioner` generates, so all of them, root schema included,
+stay consistent.
+
+```bash
+uv add fastapi-validation-override
+```
+
+```python
+from fastapi_validation_override import override_validation_error, patch_422_responses
+
+# 1. Registers the runtime handler and patches the app's own root /openapi.json.
+override_validation_error(app, status_code=400)
+
+# 2. Re-applies the same patch to each version's own schema.
+def versioning_openapi_hook(schema: dict, version: tuple[int, int]) -> dict:
+    return patch_422_responses(schema, "400")
+
+RouterVersioner(
+    app=app,
+    routers=router,
+    version_format=VersionFormat.SEMVER,
+    openapi_hook=versioning_openapi_hook,
+).versionize()
+# Validation failures now return 400, both at runtime and in every schema
+# (root, and every /vX_Y/openapi.json)
+```
+
+See [`examples/validation_override_integration_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_override_integration_app.py).
+
 ### OpenAPI Callbacks and Webhooks
 
 Route-level **Callbacks** need no special handling: a `callbacks=[...]` argument on a route
@@ -342,63 +383,18 @@ RouterVersioner(
 [`examples/download_static_assets.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/download_static_assets.py) downloads the required files in one step;
 [`examples/self_hosted_docs_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/self_hosted_docs_app.py) wires them into a full app.
 
-### Validation error status code
-
-`validation_error_code` changes what FastAPI returns for a failed request body/query/path
-validation, `422` by default, both at runtime and in the schema:
-
-```python
-RouterVersioner(
-    app=app,
-    routers=router,
-    version_format=VersionFormat.SEMVER,
-    validation_error_code=400,
-).versionize()
-# Validation failures now return 400; every 422 entry in the schema becomes 400
-```
-
-Set `handle_validation_exceptions=False` to keep the schema change while writing your own
-response body:
-
-```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; the handler above owns the response
-).versionize()
-```
-
-This also patches the app's own root `/docs`, `/redoc`, and `/openapi.json`, not just the
-versioned ones, so there's nothing left showing the stale `422`.
-
 Sharing one app across several `RouterVersioner` instances only makes sense for one reason:
 mixing `version_format` values, SemVer for one group of routes and CalVer for another, on
 the same app. Splitting modules that share a `version_format` doesn't need a second instance;
 pass them all to one `RouterVersioner` via `routers=[...]` instead (see
 [`multi_router_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/multi_router_app.py)).
-If you do share an app across instances, two rules are enforced for you:
-
-- Every instance with `handle_validation_exceptions=True` must agree on
-  `validation_error_code`. FastAPI's exception handler is registered once per app, not per
-  router, so a mismatch raises `RuntimeError` when the second instance is constructed rather
-  than silently keeping whichever handler was registered first.
-- Every instance needs its own `prefix_format`/`latest_prefix`. Two instances that resolve to
-  the same prefix would otherwise overwrite each other's docs/openapi routes at the same
-  path; this raises `RuntimeError` too.
+If you do share an app across instances, one rule is enforced for you: every instance needs
+its own `prefix_format`/`latest_prefix`. Two instances that resolve to the same prefix would
+otherwise overwrite each other's docs/openapi routes at the same path; this raises
+`RuntimeError`.
 
-For modules that genuinely don't need to coordinate at all, including a different
-`validation_error_code` each, mount them as separate FastAPI sub-applications instead (next
-section).
+For modules that genuinely don't need to coordinate at all, mount them as separate FastAPI
+sub-applications instead (next section).
 
 ### Reverse proxy and sub-application mounting
 
@@ -413,7 +409,7 @@ parent.mount("/api", app)  # root_path="/api" is injected per request
 
 A mounted sub-application is a separate `FastAPI()` instance with its own `app.state`, so a
 `RouterVersioner` attached to it is entirely independent from one attached to the parent, or
-to another sub-application, no shared `validation_error_code`, no prefix coordination needed.
+to another sub-application, no prefix coordination needed.
 See [`examples/mounted_subapps_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/mounted_subapps_app.py).
 
 ### Callback hook
@@ -446,9 +442,8 @@ RouterVersioner(
 | [`multi_router_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/multi_router_app.py) | Several routers versioned together under one instance |
 | [`self_hosted_docs_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/self_hosted_docs_app.py) | Swagger UI and ReDoc served from local static assets |
 | [`openapi_hook_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/openapi_hook_app.py) | Per-version OpenAPI schema edits via `openapi_hook` |
-| [`validation_error_code_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_error_code_app.py) | `400` instead of `422`, handled automatically by `RouterVersioner` |
-| [`validation_error_code_custom_handler_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_error_code_custom_handler_app.py) | Same, but with `handle_validation_exceptions=False` and a custom handler |
 | [`mounted_subapps_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/mounted_subapps_app.py) | Independently versioned modules as separate `app.mount()` sub-applications |
+| [`validation_override_integration_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_override_integration_app.py) | Custom validation error status code via `fastapi-validation-override` and `openapi_hook` |
 
 ---