fastapi-router-versioning 0.1.0__tar.gz → 0.1.2__tar.gz

fastapi_router_versioning-0.1.2/.github/workflows/prepare-release.yml

@@ -0,0 +1,81 @@
+name: Prepare Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Release bump
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      date:
+        description: Release date in YYYY-MM-DD format. Defaults to today.
+        required: false
+        type: string
+
+permissions: {}
+
+env:
+  PREPARE_RELEASE_VERSION_FILE: fastapi_router_versioning/__init__.py
+  PREPARE_RELEASE_RELEASE_NOTES_FILE: RELEASE_NOTES.md
+
+jobs:
+  prepare-release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: true
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version-file: ".python-version"
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.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"
+      - name: Prepare release
+        env:
+          PREPARE_RELEASE_BUMP: ${{ inputs.bump }}
+          PREPARE_RELEASE_DATE: ${{ inputs.date }}
+        run: uv run python scripts/prepare_release.py prepare
+      - name: Get release version
+        id: release-version
+        run: |
+          version="$(uv run python scripts/prepare_release.py current-version)"
+          echo "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - name: Ensure release label exists
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh label create release --color 0075ca --description "Release PR" 2>/dev/null || true
+      - name: Create release pull request
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ steps.release-version.outputs.version }}
+        run: |
+          set -euo pipefail
+          branch="release-${VERSION}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git switch -c "$branch"
+          git add $PREPARE_RELEASE_VERSION_FILE $PREPARE_RELEASE_RELEASE_NOTES_FILE
+          git commit -m "🔖 Release version ${VERSION}"
+          git push --set-upstream origin "$branch"
+          gh pr create \
+            --base main \
+            --head "$branch" \
+            --title "🔖 Release version ${VERSION}" \
+            --body "Prepare release ${VERSION}." \
+            --label release

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/.github/workflows/test-redistribute.yml

@@ -12,7 +12,33 @@ on:
 permissions: {}
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    timeout-minutes: 5
+    outputs:
+      src: ${{ steps.filter.outputs.src }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        id: filter
+        with:
+          filters: |
+            src:
+              - .github/workflows/test-redistribute.yml
+              - fastapi_router_versioning/**
+              - tests/**
+              - .python-version
+              - pyproject.toml
+              - uv.lock
+
   test-redistribute:
+    needs:
+      - changes
+    if: needs.changes.outputs.src == 'true' || github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
@@ -49,10 +75,6 @@ jobs:
         run: |
           cd dist
           pip wheel --no-deps fastapi_router_versioning*.tar.gz
-      - name: Dump GitHub context
-        env:
-          GITHUB_CONTEXT: ${{ toJson(github) }}
-        run: echo "$GITHUB_CONTEXT"
 
   # https://github.com/marketplace/actions/alls-green#why
   test-redistribute-alls-green:
@@ -66,3 +88,4 @@ jobs:
         uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
         with:
           jobs: ${{ toJSON(needs) }}
+          allowed-skips: test-redistribute

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/.github/workflows/test.yml

@@ -17,7 +17,34 @@ env:
   UV_NO_SYNC: true
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    timeout-minutes: 5
+    outputs:
+      src: ${{ steps.filter.outputs.src }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        id: filter
+        with:
+          filters: |
+            src:
+              - .github/workflows/test.yml
+              - fastapi_router_versioning/**
+              - scripts/**
+              - tests/**
+              - .python-version
+              - pyproject.toml
+              - uv.lock
+
   test:
+    needs:
+      - changes
+    if: needs.changes.outputs.src == 'true' || github.ref == 'refs/heads/main'
     timeout-minutes: 15
     permissions:
       contents: read
@@ -134,6 +161,7 @@ jobs:
   check:
     if: always()
     needs:
+      - test
       - coverage-combine
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -143,3 +171,4 @@ jobs:
         uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
         with:
           jobs: ${{ toJSON(needs) }}
+          allowed-skips: test,coverage-combine

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: fastapi-router-versioning
-Version: 0.1.0
-Summary: Native, router-based API versioning for FastAPI, featuring per-version docs and a declarative route lifecycle.
+Version: 0.1.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
 Project-URL: Issues, https://github.com/mat81black/fastapi-router-versioning/issues
@@ -26,15 +26,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.
 
 ---
 
@@ -93,7 +93,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 +117,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.
 
 ---
 
@@ -181,8 +181,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 +278,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 +325,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 +343,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 +359,7 @@ 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.
 
 ### Reverse proxy / sub-app mounting
 

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/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.
 
 ---
 
@@ -65,7 +65,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 +89,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.
 
 ---
 
@@ -153,8 +153,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 +250,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 +297,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 +315,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 +331,7 @@ 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.
 
 ### Reverse proxy / sub-app mounting
 

fastapi_router_versioning-0.1.2/RELEASE_NOTES.md

@@ -0,0 +1,47 @@
+# Release Notes
+
+## Latest Changes
+
+## 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.0 → fastapi_router_versioning-0.1.2}/fastapi_router_versioning/__init__.py

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

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/fastapi_router_versioning/versioner.py

@@ -37,8 +37,15 @@ def _iter_routes_flat(routes: list[Any]) -> Iterator[Any]:
         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
+            yield original  # pragma: no cover
 
 
 def _unwrap_route(route: Any) -> Any:
@@ -195,6 +202,8 @@ class RouterVersioner:
         self._redoc_js_url = redoc_js_url
         self._redoc_favicon_url = redoc_favicon_url
         self._redoc_with_google_fonts = redoc_with_google_fonts
+        self._openapi_schemas_cache: dict[VersionT, dict[str, Any]] = {}
+        self._openapi_routes_versions: dict[VersionT, int | None] = {}
 
         if default_version is None:
             self._default_version: VersionT = (1, 0) if version_format == VersionFormat.SEMVER else "1"
@@ -363,9 +372,8 @@ class RouterVersioner:
         if not webhooks_by_version:
             # webhook_routers not provided: fall back to global app.webhooks
             return list(self._app.webhooks.routes)
-        candidates: list[VersionT] = []
         if isinstance(version, tuple):
-            candidates = [v for v in webhooks_by_version if isinstance(v, tuple) and v <= version]
+            candidates: list[VersionT] = [v for v in webhooks_by_version if isinstance(v, tuple) and v <= version]
         else:
             candidates = [v for v in webhooks_by_version if isinstance(v, str) and v <= version]
         if not candidates:
@@ -424,23 +432,38 @@ class RouterVersioner:
     ) -> None:
         @router.get(openapi_url, include_in_schema=False)
         async def get_openapi(req: Request) -> Any:
-            schema = fastapi.openapi.utils.get_openapi(
-                title=title,
-                version=doc_version_str,
-                openapi_version=self._app.openapi_version,
-                summary=self._app.summary,
-                description=self._app.description,
-                routes=router.routes,
-                webhooks=webhooks,
-                tags=versioned_tags,
-                servers=self._app.servers,
-                terms_of_service=self._app.terms_of_service,
-                contact=self._app.contact,
-                license_info=self._app.license_info,
-                separate_input_output_schemas=self._app.separate_input_output_schemas,
-                external_docs=self._app.openapi_external_docs,
-            )
-
+            # _get_routes_version() is the same internal FastAPI uses for its own schema cache;
+            # if unavailable (private API removed), current_routes_version stays None and the
+            # cache persists indefinitely — degraded but correct.
+            _get_routes_version = getattr(router, "_get_routes_version", None)
+            current_routes_version = _get_routes_version() if _get_routes_version else None
+
+            cached = self._openapi_schemas_cache.get(version)
+            if cached is None or self._openapi_routes_versions.get(version) != current_routes_version:
+                schema = fastapi.openapi.utils.get_openapi(
+                    title=title,
+                    version=doc_version_str,
+                    openapi_version=self._app.openapi_version,
+                    summary=self._app.summary,
+                    description=self._app.description,
+                    routes=router.routes,
+                    webhooks=webhooks,
+                    tags=versioned_tags,
+                    servers=self._app.servers,
+                    terms_of_service=self._app.terms_of_service,
+                    contact=self._app.contact,
+                    license_info=self._app.license_info,
+                    separate_input_output_schemas=self._app.separate_input_output_schemas,
+                    external_docs=self._app.openapi_external_docs,
+                )
+                if self._openapi_hook is not None:
+                    schema = self._openapi_hook(schema, version)
+                self._openapi_schemas_cache[version] = schema
+                self._openapi_routes_versions[version] = current_routes_version
+            else:
+                schema = self._openapi_schemas_cache[version]
+
+            # root_path is per-request: shallow copy to avoid polluting the cache
             root_path = req.scope.get("root_path", "").rstrip("/")
             if root_path and getattr(self._app, "root_path_in_servers", True):
                 server_urls = {s.get("url") for s in schema.get("servers", [])}
@@ -448,9 +471,6 @@ class RouterVersioner:
                     schema = dict(schema)
                     schema["servers"] = [{"url": root_path}] + schema.get("servers", [])
 
-            if self._openapi_hook is not None:
-                schema = self._openapi_hook(schema, version)
-
             return schema
 
     def _add_swagger_ui_routes(

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "fastapi-router-versioning"
 dynamic = ["version"]
-description = "Native, router-based API versioning for FastAPI, featuring per-version docs and a declarative route lifecycle."
+description = "Router-based API versioning for FastAPI, with per-version docs and a declarative route lifecycle."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -52,6 +52,7 @@ dev = [
     "prek >=0.2.22",
     "ty>=0.0.28",
     "pyrefly>=0.60.0",
+    "typer>=0.15.0",
     "uvicorn>=0.49.0",
     "zizmor>=1.0.0",
 ]

fastapi_router_versioning-0.1.2/scripts/prepare_release.py

@@ -0,0 +1,189 @@
+"""Prepare a release by updating the package version and release notes."""
+
+import re
+
+from datetime import date
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+
+VERSION_PATTERN = re.compile(r'(?m)^__version__ = "(\d+\.\d+\.\d+)"$')
+VERSION_HEADING_PATTERN = re.compile(r"(?m)^## (\d+\.\d+\.\d+)(?: \([^)]+\))?$")
+RELEASE_NOTES_HEADER = "# Release Notes\n\n"
+LATEST_CHANGES_HEADER = "## Latest Changes"
+BumpType = Literal["major", "minor", "patch"]
+
+app = typer.Typer()
+
+
+def parse_version(version: str) -> tuple[int, int, int]:
+    match = re.fullmatch(r"\d+\.\d+\.\d+", version)
+    if not match:
+        raise ValueError(f"Invalid version: {version!r}. Expected format: X.Y.Z")
+    major, minor, patch = version.split(".")
+    return int(major), int(minor), int(patch)
+
+
+def get_current_version(content: str, version_file: Path) -> str:
+    matches = list(VERSION_PATTERN.finditer(content))
+    if len(matches) != 1:
+        raise RuntimeError(f"Expected exactly one __version__ assignment in {version_file}, found {len(matches)}")
+    return matches[0].group(1)
+
+
+def bump_version(version: str, bump: BumpType) -> str:
+    major, minor, patch = parse_version(version)
+    if bump == "major":
+        return f"{major + 1}.0.0"
+    if bump == "minor":
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def update_version_file(content: str, version: str, version_file: Path) -> str:
+    current_version = get_current_version(content, version_file)
+    if parse_version(version) <= parse_version(current_version):
+        raise RuntimeError(f"New version {version} must be greater than current version {current_version}")
+    return VERSION_PATTERN.sub(f'__version__ = "{version}"', content, count=1)
+
+
+def update_release_notes(content: str, version: str, release_date: date, release_notes_file: Path) -> str:
+    if not content.startswith(RELEASE_NOTES_HEADER):
+        raise RuntimeError(f"{release_notes_file} must start with {RELEASE_NOTES_HEADER!r}")
+    if re.search(rf"^## {re.escape(version)}(?: \([^)]+\))?$", content, re.M):
+        raise RuntimeError(f"Release notes already contain a section for {version}")
+
+    latest_header = f"{RELEASE_NOTES_HEADER}{LATEST_CHANGES_HEADER}\n"
+    if not content.startswith(latest_header):
+        raise RuntimeError(f"{release_notes_file} must start with {latest_header!r}")
+
+    release_header = f"## {version} ({release_date.isoformat()})"
+    return content.replace(
+        latest_header,
+        f"{RELEASE_NOTES_HEADER}{LATEST_CHANGES_HEADER}\n\n{release_header}\n",
+        1,
+    )
+
+
+def get_release_notes_body(content: str, version: str, release_notes_file: Path) -> str:
+    version_heading = re.compile(rf"(?m)^## {re.escape(version)}(?: \([^)]+\))?$")
+    match = version_heading.search(content)
+    if not match:
+        raise RuntimeError(f"Could not find release notes section for {version} in {release_notes_file}")
+
+    next_match = VERSION_HEADING_PATTERN.search(content, match.end())
+    end = next_match.start() if next_match else len(content)
+    body = content[match.end() : end].strip()
+    if not body:
+        raise RuntimeError(f"Release notes section for {version} in {release_notes_file} is empty")
+    return f"{body}\n"
+
+
+@app.command()
+def prepare(
+    bump: Annotated[
+        BumpType,
+        typer.Argument(
+            envvar="PREPARE_RELEASE_BUMP",
+            help="The release bump to make: major, minor, or patch.",
+        ),
+    ],
+    version_file: Annotated[
+        Path,
+        typer.Option(
+            envvar="PREPARE_RELEASE_VERSION_FILE",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            writable=True,
+            help="Path to the Python file containing the __version__ assignment.",
+        ),
+    ],
+    release_notes_file: Annotated[
+        Path,
+        typer.Option(
+            envvar="PREPARE_RELEASE_RELEASE_NOTES_FILE",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            writable=True,
+            help="Path to the release notes Markdown file.",
+        ),
+    ],
+    release_date: Annotated[
+        str,
+        typer.Option(
+            "--date",
+            envvar="PREPARE_RELEASE_DATE",
+            help="Release date in YYYY-MM-DD format. Defaults to today.",
+        ),
+    ] = date.today().isoformat(),
+) -> None:
+    parsed_release_date = date.fromisoformat(release_date or date.today().isoformat())
+
+    version_file_content = version_file.read_text()
+    release_notes_content = release_notes_file.read_text()
+    version = bump_version(get_current_version(version_file_content, version_file), bump)
+
+    version_file.write_text(update_version_file(version_file_content, version, version_file))
+    release_notes_file.write_text(
+        update_release_notes(release_notes_content, version, parsed_release_date, release_notes_file)
+    )
+
+    typer.echo(f"Prepared release {version} ({parsed_release_date.isoformat()})")
+
+
+@app.command()
+def current_version(
+    version_file: Annotated[
+        Path,
+        typer.Option(
+            envvar="PREPARE_RELEASE_VERSION_FILE",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="Path to the Python file containing the __version__ assignment.",
+        ),
+    ],
+) -> None:
+    typer.echo(get_current_version(version_file.read_text(), version_file))
+
+
+@app.command()
+def release_notes(
+    version_file: Annotated[
+        Path,
+        typer.Option(
+            envvar="PREPARE_RELEASE_VERSION_FILE",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="Path to the Python file containing the __version__ assignment.",
+        ),
+    ],
+    release_notes_file: Annotated[
+        Path,
+        typer.Option(
+            envvar="PREPARE_RELEASE_RELEASE_NOTES_FILE",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="Path to the release notes Markdown file.",
+        ),
+    ],
+) -> None:
+    version = get_current_version(version_file.read_text(), version_file)
+    typer.echo(
+        get_release_notes_body(release_notes_file.read_text(), version, release_notes_file),
+        nl=False,
+    )
+
+
+if __name__ == "__main__":
+    app()

fastapi_router_versioning-0.1.2/tests/test_prepare_release.py

@@ -0,0 +1,211 @@
+"""Tests for scripts/prepare_release.py."""
+
+from pathlib import Path
+
+import pytest
+
+from typer.testing import CliRunner
+
+from scripts.prepare_release import app
+
+runner = CliRunner()
+
+INIT_TEMPLATE = '__version__ = "{version}"\n'
+NOTES_TEMPLATE = "# Release Notes\n\n## Latest Changes\n\n## 0.1.0 (2025-01-01)\n\nInitial release.\n"
+
+
+@pytest.fixture()
+def version_file(tmp_path: Path) -> Path:
+    f = tmp_path / "__init__.py"
+    f.write_text(INIT_TEMPLATE.format(version="0.1.0"))
+    return f
+
+
+@pytest.fixture()
+def notes_file(tmp_path: Path) -> Path:
+    f = tmp_path / "RELEASE_NOTES.md"
+    f.write_text(NOTES_TEMPLATE)
+    return f
+
+
+# ---------------------------------------------------------------------------
+# current-version
+# ---------------------------------------------------------------------------
+
+
+def test_current_version(version_file: Path) -> None:
+    result = runner.invoke(app, ["current-version", "--version-file", str(version_file)])
+    assert result.exit_code == 0
+    assert result.output.strip() == "0.1.0"
+
+
+# ---------------------------------------------------------------------------
+# prepare
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("bump", "expected"),
+    [
+        ("patch", "0.1.1"),
+        ("minor", "0.2.0"),
+        ("major", "1.0.0"),
+    ],
+)
+def test_prepare_bump(
+    version_file: Path,
+    notes_file: Path,
+    bump: str,
+    expected: str,
+) -> None:
+    result = runner.invoke(
+        app,
+        [
+            "prepare",
+            bump,
+            "--version-file",
+            str(version_file),
+            "--release-notes-file",
+            str(notes_file),
+            "--date",
+            "2026-01-01",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert f'__version__ = "{expected}"' in version_file.read_text()
+
+
+def test_prepare_updates_release_notes(version_file: Path, notes_file: Path) -> None:
+    runner.invoke(
+        app,
+        [
+            "prepare",
+            "minor",
+            "--version-file",
+            str(version_file),
+            "--release-notes-file",
+            str(notes_file),
+            "--date",
+            "2026-06-01",
+        ],
+    )
+    notes = notes_file.read_text()
+    assert "## Latest Changes" in notes
+    assert "## 0.2.0 (2026-06-01)" in notes
+
+
+def test_prepare_version_must_increase(version_file: Path, notes_file: Path) -> None:
+    # bump to 0.2.0 first
+    runner.invoke(
+        app,
+        [
+            "prepare",
+            "minor",
+            "--version-file",
+            str(version_file),
+            "--release-notes-file",
+            str(notes_file),
+            "--date",
+            "2026-01-01",
+        ],
+    )
+    # write a fresh notes file — otherwise "already contains section" fires first
+    notes_file.write_text(NOTES_TEMPLATE)
+    # try to bump patch on already-bumped file: 0.2.0 patch → 0.2.1, which is valid.
+    # To trigger the guard, manually set version higher than what bump produces.
+    version_file.write_text(INIT_TEMPLATE.format(version="0.2.0"))
+    # writing 0.2.0 again via a fake bump isn't easy via CLI, so test the helper directly
+    from scripts.prepare_release import update_version_file
+
+    content = version_file.read_text()
+    with pytest.raises(RuntimeError, match="must be greater than"):
+        update_version_file(content, "0.2.0", version_file)
+
+
+def test_prepare_section_already_exists(version_file: Path, notes_file: Path) -> None:
+    # bump once
+    runner.invoke(
+        app,
+        [
+            "prepare",
+            "minor",
+            "--version-file",
+            str(version_file),
+            "--release-notes-file",
+            str(notes_file),
+            "--date",
+            "2026-01-01",
+        ],
+    )
+    # restore version so bump produces the same version again
+    version_file.write_text(INIT_TEMPLATE.format(version="0.1.0"))
+    result = runner.invoke(
+        app,
+        [
+            "prepare",
+            "minor",
+            "--version-file",
+            str(version_file),
+            "--release-notes-file",
+            str(notes_file),
+            "--date",
+            "2026-01-01",
+        ],
+    )
+    assert result.exit_code != 0
+
+
+def test_prepare_notes_wrong_header(version_file: Path, tmp_path: Path) -> None:
+    bad_notes = tmp_path / "RELEASE_NOTES.md"
+    bad_notes.write_text("## Latest Changes\n\n## 0.1.0\n\nInitial release.\n")
+    result = runner.invoke(
+        app,
+        ["prepare", "minor", "--version-file", str(version_file), "--release-notes-file", str(bad_notes)],
+    )
+    assert result.exit_code != 0
+
+
+def test_prepare_notes_missing_latest_changes(version_file: Path, tmp_path: Path) -> None:
+    bad_notes = tmp_path / "RELEASE_NOTES.md"
+    bad_notes.write_text("# Release Notes\n\n## 0.1.0\n\nInitial release.\n")
+    result = runner.invoke(
+        app,
+        ["prepare", "minor", "--version-file", str(version_file), "--release-notes-file", str(bad_notes)],
+    )
+    assert result.exit_code != 0
+
+
+# ---------------------------------------------------------------------------
+# release-notes
+# ---------------------------------------------------------------------------
+
+
+def test_release_notes_extracts_body(version_file: Path, tmp_path: Path) -> None:
+    notes = tmp_path / "RELEASE_NOTES.md"
+    notes.write_text("# Release Notes\n\n## Latest Changes\n\n## 0.1.0 (2025-01-01)\n\nInitial release.\n")
+    result = runner.invoke(
+        app,
+        ["release-notes", "--version-file", str(version_file), "--release-notes-file", str(notes)],
+    )
+    assert result.exit_code == 0, result.output
+    assert result.output.strip() == "Initial release."
+
+
+def test_release_notes_missing_section(version_file: Path, tmp_path: Path) -> None:
+    notes = tmp_path / "RELEASE_NOTES.md"
+    notes.write_text("# Release Notes\n\n## Latest Changes\n\n## 0.2.0 (2025-01-01)\n\nSomething.\n")
+    result = runner.invoke(
+        app,
+        ["release-notes", "--version-file", str(version_file), "--release-notes-file", str(notes)],
+    )
+    assert result.exit_code != 0
+
+
+def test_release_notes_empty_section(version_file: Path, tmp_path: Path) -> None:
+    notes = tmp_path / "RELEASE_NOTES.md"
+    notes.write_text("# Release Notes\n\n## Latest Changes\n\n## 0.1.0 (2025-01-01)\n")
+    result = runner.invoke(
+        app,
+        ["release-notes", "--version-file", str(version_file), "--release-notes-file", str(notes)],
+    )
+    assert result.exit_code != 0

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/tests/test_versioner.py

@@ -129,6 +129,28 @@ def test_websockets_versioning() -> None:
         assert data == "Hello Versioned WS"
 
 
+def test_websocket_nested_router_prefix_is_preserved() -> None:
+    """WebSocket inside a sub-router with a prefix must carry the full merged path when versionized."""
+    app = FastAPI()
+    ws_router = APIRouter()
+
+    @ws_router.websocket("/ws")
+    @api_version((1, 0))
+    async def ws_endpoint(websocket: WebSocket) -> None:
+        await websocket.accept()
+        await websocket.send_text("ok")
+        await websocket.close()
+
+    parent_router = APIRouter(prefix="/chat")
+    parent_router.include_router(ws_router)
+
+    RouterVersioner(app=app, routers=parent_router, version_format=VersionFormat.SEMVER).versionize()
+
+    client = TestClient(app)
+    with client.websocket_connect("/v1_0/chat/ws") as ws:
+        assert ws.receive_text() == "ok"
+
+
 def test_unsupported_route_type_raises_error() -> None:
     """A Starlette Route (not APIRoute/APIWebSocketRoute) should raise TypeError."""
     app = FastAPI()
@@ -812,6 +834,65 @@ def test_webhook_routers_calver() -> None:
     assert "/event" in schema.get("webhooks", {})
 
 
+def test_openapi_schema_is_cached() -> None:
+    """The schema is generated only once; subsequent requests use the cache."""
+    from unittest.mock import patch
+
+    import fastapi.openapi.utils as openapi_utils
+
+    app = FastAPI()
+    router = APIRouter()
+
+    @router.get("/data")
+    @api_version((1, 0))
+    def get_data() -> dict[str, str]: ...
+
+    RouterVersioner(app=app, routers=router, version_format=VersionFormat.SEMVER).versionize()
+    client = TestClient(app)
+
+    with patch.object(openapi_utils, "get_openapi", wraps=openapi_utils.get_openapi) as mock_fn:
+        client.get("/v1_0/openapi.json")
+        client.get("/v1_0/openapi.json")
+        assert mock_fn.call_count == 1
+
+
+def test_openapi_cache_invalidated_on_route_change() -> None:
+    """The cache is invalidated when _get_routes_version() changes after a new route is added."""
+    from unittest.mock import patch
+
+    import fastapi.openapi.utils as openapi_utils
+
+    import fastapi_router_versioning.versioner as versioner_mod
+
+    if versioner_mod._route_contexts_fn is None:
+        pytest.skip("_get_routes_version not available (FastAPI < 0.137.2)")  # pragma: no cover
+
+    app = FastAPI()
+    router = APIRouter()
+
+    @router.get("/data")
+    @api_version((1, 0))
+    def get_data() -> dict[str, str]: ...
+
+    captured_routers: dict[Any, APIRouter] = {}
+
+    def capture_callback(versioned_router: APIRouter, version: VersionT, prefix: str) -> None:
+        captured_routers[version] = versioned_router
+
+    versioner = RouterVersioner(app=app, routers=router, version_format=VersionFormat.SEMVER, callback=capture_callback)
+    versioner.versionize()
+    client = TestClient(app)
+
+    with patch.object(openapi_utils, "get_openapi", wraps=openapi_utils.get_openapi) as mock_fn:
+        client.get("/v1_0/openapi.json")
+        assert mock_fn.call_count == 1
+
+        captured_routers[(1, 0)].add_api_route("/dynamic", lambda: {}, methods=["GET"])
+
+        client.get("/v1_0/openapi.json")
+        assert mock_fn.call_count == 2
+
+
 def test_iter_routes_flat_fallback_without_route_context_fn() -> None:
     """Covers the _route_contexts_fn=None fallback (legacy FastAPI < 0.137.2).
 

{fastapi_router_versioning-0.1.0 → fastapi_router_versioning-0.1.2}/uv.lock

@@ -302,6 +302,7 @@ dev = [
     { name = "pytest-dotenv" },
     { name = "ruff" },
     { name = "ty" },
+    { name = "typer" },
     { name = "uvicorn" },
     { name = "zizmor" },
 ]
@@ -323,6 +324,7 @@ dev = [
     { name = "pytest-dotenv", specifier = ">=0.5.2" },
     { name = "ruff", specifier = ">=0.14.0" },
     { name = "ty", specifier = ">=0.0.28" },
+    { name = "typer", specifier = ">=0.15.0" },
     { name = "uvicorn", specifier = ">=0.49.0" },
     { name = "zizmor", specifier = ">=1.0.0" },
 ]
@@ -904,6 +906,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/29/4c/67bb45e41609eb4726f1bfeb59e083cf91d14c696d4bd14c234a980be93d/ruff-0.15.18-py3-none-win_arm64.whl", hash = "sha256:b2c9257fcbd4a3e5b977a1904e6facca016bafe2edc17df24db67cfaee03b4e4", size = 11329958, upload-time = "2026-06-18T18:25:43.686Z" },
 ]
 
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
+]
+
 [[package]]
 name = "starlette"
 version = "1.3.1"
@@ -1005,6 +1016,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/50/b5/d49096cd5f3694becb86a5a6ccd0f229ead695fc7430d6bc4dd0a104c6fe/ty-0.0.51-py3-none-win_arm64.whl", hash = "sha256:62ced5e380284f12b2dc4802a3e4ed3dac39913fc6719afde7978814a4c7f169", size = 11657350, upload-time = "2026-06-19T01:48:55.904Z" },
 ]
 
+[[package]]
+name = "typer"
+version = "0.26.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "rich" },
+    { name = "shellingham" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5e/ed/ef06584ccdd5c410df0837951ecd7e15d9a6144ea1bd4c73cecab1a89891/typer-0.26.7.tar.gz", hash = "sha256:e314a34c617e419c091b2830dda3ea1f257134ff593061a8f5b9717ab8dddb3a", size = 201709, upload-time = "2026-06-03T07:18:06.843Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/2201973529af2c954de0bb725323c3aaed6d7f0ceee8f550dec9185df013/typer-0.26.7-py3-none-any.whl", hash = "sha256:5c87cfbc5d34491c5346ebf49c23e18d56ccb863268d3a8d592b26087c2f5e58", size = 122456, upload-time = "2026-06-03T07:18:05.732Z" },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.15.0"