fastapi-router-versioning 1.2.0__tar.gz → 1.2.1__tar.gz

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/.github/workflows/bump-pre-commit-hooks.yml

@@ -9,7 +9,7 @@ permissions: {}
 
 jobs:
   bump-pre-commit-hooks:
-    if: github.repository_owner == 'mat81black'
+    if: github.repository_owner == 'matblack81'
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: fastapi-router-versioning
-Version: 1.2.0
+Version: 1.2.1
 Summary: Router-based API versioning for FastAPI, with per-version docs and a declarative route lifecycle.
-Project-URL: Homepage, https://mat81black.github.io/fastapi-router-versioning/
-Project-URL: Repository, https://github.com/mat81black/fastapi-router-versioning
-Project-URL: Issues, https://github.com/mat81black/fastapi-router-versioning/issues
-Project-URL: Documentation, https://mat81black.github.io/fastapi-router-versioning/
-Project-URL: Changelog, https://mat81black.github.io/fastapi-router-versioning/release-notes/
+Project-URL: Homepage, https://fastapi-router-versioning.matblack81.com/
+Project-URL: Repository, https://github.com/matblack81/fastapi-router-versioning
+Project-URL: Issues, https://github.com/matblack81/fastapi-router-versioning/issues
+Project-URL: Documentation, https://fastapi-router-versioning.matblack81.com/
+Project-URL: Changelog, https://fastapi-router-versioning.matblack81.com/release-notes/
 Author-email: Matteo Nieddu <mat81black@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -31,24 +31,24 @@ Requires-Dist: fastapi!=0.137.0,!=0.137.1,>=0.120.0
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mat81black/fastapi-router-versioning/main/docs/assets/images/logo.svg" alt="FastAPI Router Versioning logo" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/matblack81/fastapi-router-versioning/main/docs/assets/images/logo.svg" alt="FastAPI Router Versioning logo" width="128">
 </p>
 
 <h1 align="center">
-  <img src="https://raw.githubusercontent.com/mat81black/fastapi-router-versioning/main/docs/assets/images/wordmark.png" alt="FastAPI Router Versioning" width="480">
+  <img src="https://raw.githubusercontent.com/matblack81/fastapi-router-versioning/main/docs/assets/images/wordmark.png" alt="FastAPI Router Versioning" width="480">
 </h1>
 
 <p align="center">
-  <a href="https://github.com/mat81black/fastapi-router-versioning/actions"><img src="https://github.com/mat81black/fastapi-router-versioning/workflows/Test/badge.svg" alt="Build Status"></a>
-  <a href="https://codecov.io/github/mat81black/fastapi-router-versioning"><img src="https://codecov.io/github/mat81black/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY" alt="codecov"></a>
+  <a href="https://github.com/matblack81/fastapi-router-versioning/actions"><img src="https://github.com/matblack81/fastapi-router-versioning/workflows/Test/badge.svg" alt="Build Status"></a>
+  <a href="https://codecov.io/github/matblack81/fastapi-router-versioning"><img src="https://codecov.io/github/matblack81/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY" alt="codecov"></a>
   <a href="https://pypi.org/project/fastapi-router-versioning/"><img src="https://img.shields.io/pypi/v/fastapi-router-versioning?color=%2334D058&label=pypi%20package" alt="pypi package"></a>
   <a href="https://pypi.org/project/fastapi-router-versioning/"><img src="https://img.shields.io/pypi/pyversions/fastapi-router-versioning.svg?color=%2334D058" alt="Supported Python versions"></a>
-  <a href="https://github.com/mat81black/fastapi-router-versioning/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
+  <a href="https://github.com/matblack81/fastapi-router-versioning/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
 </p>
 
 Running multiple API versions side by side usually means duplicating routers, hand-rolling prefixes, or branching on request paths. `RouterVersioner` does it declaratively instead: annotate each route with the version it belongs to, and it generates the URL prefixes, the per-version OpenAPI schema, and the docs, without moving anything else in your app.
 
-Documentation: https://mat81black.github.io/fastapi-router-versioning/
+Documentation: https://fastapi-router-versioning.matblack81.com/
 
 ---
 
@@ -122,16 +122,16 @@ RouterVersioner(
 ).versionize()
 ```
 
-CalVer, the route lifecycle, the parameter reference and the advanced options are in the [documentation](https://mat81black.github.io/fastapi-router-versioning/).
+CalVer, the route lifecycle, the parameter reference and the advanced options are in the [documentation](https://fastapi-router-versioning.matblack81.com/).
 
 ---
 
 ## Release Notes
 
-[RELEASE_NOTES](https://github.com/mat81black/fastapi-router-versioning/blob/main/docs/release-notes.md)
+[RELEASE_NOTES](https://github.com/matblack81/fastapi-router-versioning/blob/main/docs/release-notes.md)
 
 ---
 
 ## License
 
-[MIT](https://github.com/mat81black/fastapi-router-versioning/blob/main/LICENSE)
+[MIT](https://github.com/matblack81/fastapi-router-versioning/blob/main/LICENSE)

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/README.md

@@ -1,22 +1,22 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mat81black/fastapi-router-versioning/main/docs/assets/images/logo.svg" alt="FastAPI Router Versioning logo" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/matblack81/fastapi-router-versioning/main/docs/assets/images/logo.svg" alt="FastAPI Router Versioning logo" width="128">
 </p>
 
 <h1 align="center">
-  <img src="https://raw.githubusercontent.com/mat81black/fastapi-router-versioning/main/docs/assets/images/wordmark.png" alt="FastAPI Router Versioning" width="480">
+  <img src="https://raw.githubusercontent.com/matblack81/fastapi-router-versioning/main/docs/assets/images/wordmark.png" alt="FastAPI Router Versioning" width="480">
 </h1>
 
 <p align="center">
-  <a href="https://github.com/mat81black/fastapi-router-versioning/actions"><img src="https://github.com/mat81black/fastapi-router-versioning/workflows/Test/badge.svg" alt="Build Status"></a>
-  <a href="https://codecov.io/github/mat81black/fastapi-router-versioning"><img src="https://codecov.io/github/mat81black/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY" alt="codecov"></a>
+  <a href="https://github.com/matblack81/fastapi-router-versioning/actions"><img src="https://github.com/matblack81/fastapi-router-versioning/workflows/Test/badge.svg" alt="Build Status"></a>
+  <a href="https://codecov.io/github/matblack81/fastapi-router-versioning"><img src="https://codecov.io/github/matblack81/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY" alt="codecov"></a>
   <a href="https://pypi.org/project/fastapi-router-versioning/"><img src="https://img.shields.io/pypi/v/fastapi-router-versioning?color=%2334D058&label=pypi%20package" alt="pypi package"></a>
   <a href="https://pypi.org/project/fastapi-router-versioning/"><img src="https://img.shields.io/pypi/pyversions/fastapi-router-versioning.svg?color=%2334D058" alt="Supported Python versions"></a>
-  <a href="https://github.com/mat81black/fastapi-router-versioning/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
+  <a href="https://github.com/matblack81/fastapi-router-versioning/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
 </p>
 
 Running multiple API versions side by side usually means duplicating routers, hand-rolling prefixes, or branching on request paths. `RouterVersioner` does it declaratively instead: annotate each route with the version it belongs to, and it generates the URL prefixes, the per-version OpenAPI schema, and the docs, without moving anything else in your app.
 
-Documentation: https://mat81black.github.io/fastapi-router-versioning/
+Documentation: https://fastapi-router-versioning.matblack81.com/
 
 ---
 
@@ -90,16 +90,16 @@ RouterVersioner(
 ).versionize()
 ```
 
-CalVer, the route lifecycle, the parameter reference and the advanced options are in the [documentation](https://mat81black.github.io/fastapi-router-versioning/).
+CalVer, the route lifecycle, the parameter reference and the advanced options are in the [documentation](https://fastapi-router-versioning.matblack81.com/).
 
 ---
 
 ## Release Notes
 
-[RELEASE_NOTES](https://github.com/mat81black/fastapi-router-versioning/blob/main/docs/release-notes.md)
+[RELEASE_NOTES](https://github.com/matblack81/fastapi-router-versioning/blob/main/docs/release-notes.md)
 
 ---
 
 ## License
 
-[MIT](https://github.com/mat81black/fastapi-router-versioning/blob/main/LICENSE)
+[MIT](https://github.com/matblack81/fastapi-router-versioning/blob/main/LICENSE)

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/advanced/callbacks-and-webhooks.md

@@ -19,7 +19,7 @@ each definition:
 --8<-- "docs_src/advanced/webhooks.py:snippet"
 ```
 
-In [`webhook_versioning_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/webhook_versioning_app.py), which follows this pattern, v1.0 lists two webhooks and v2.0 only `order-created`, with its v2 definition (the example's second webhook is `payment-received` rather than `payment-failed`):
+In [`webhook_versioning_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/webhook_versioning_app.py), which follows this pattern, v1.0 lists two webhooks and v2.0 only `order-created`, with its v2 definition (the example's second webhook is `payment-received` rather than `payment-failed`):
 
 === "v1.0"
 

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/advanced/deprecation-headers.md

@@ -33,4 +33,4 @@ config). `versionize()` raises `ValueError` if a route's `remove_in` date preced
 This adds nothing to `@api_version`: the lifecycle stays on the route, the dates stay on the
 versioner. `Deprecation` and `Sunset` are only set if the response doesn't already carry them:
 a route that sets its own keeps it. The `Link` field is sent alongside any the route already
-emits (RFC 8288: multiple `Link` fields combine). See [`deprecation_headers_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/deprecation_headers_app.py).
+emits (RFC 8288: multiple `Link` fields combine). See [`deprecation_headers_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/deprecation_headers_app.py).

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/advanced/multiple-routers.md

@@ -15,7 +15,7 @@ Sharing one app across several `RouterVersioner` instances only makes sense for
 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)).
+[`multi_router_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/multi_router_app.py)).
 If you do share an app across instances, one rule is enforced: 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

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/advanced/reverse-proxy-and-sub-apps.md

@@ -14,4 +14,4 @@ The ASGI `root_path` FastAPI sets when an app runs behind a proxy or is mounted
 A mounted sub-application is a separate `FastAPI()` instance, so a `RouterVersioner` attached to
 it is entirely independent from one attached to the parent, or to another sub-application, with
 no prefix coordination needed.
-See [`examples/mounted_subapps_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/mounted_subapps_app.py).
+See [`examples/mounted_subapps_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/mounted_subapps_app.py).

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/advanced/self-hosted-assets.md

@@ -11,5 +11,5 @@ copies for air-gapped or restricted-network deployments:
 --8<-- "docs_src/advanced/self_hosted_assets.py:snippet"
 ```
 
-[`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.
+[`examples/download_static_assets.py`](https://github.com/matblack81/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/matblack81/fastapi-router-versioning/blob/main/examples/self_hosted_docs_app.py) wires them into a full app.

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/advanced/validation-error-status-code.md

@@ -19,4 +19,4 @@ uv add fastapi-validation-override
 --8<-- "docs_src/advanced/validation_error_status_code.py:snippet"
 ```
 
-See [`examples/validation_override_integration_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/validation_override_integration_app.py).
+See [`examples/validation_override_integration_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/validation_override_integration_app.py).

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/advanced/version-discovery.md

@@ -46,4 +46,4 @@ if you want them).
 
 ![The built-in versions dashboard: two versions, each with links to Swagger, ReDoc and OpenAPI, and a Guide link on the second](../assets/screenshots/versions-dashboard.jpg)
 
-The built-in dashboard, from [`versions_dashboard_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/versions_dashboard_app.py).
+The built-in dashboard, from [`versions_dashboard_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/versions_dashboard_app.py).

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/examples.md

@@ -128,4 +128,4 @@ Custom validation error status code via `fastapi-validation-override` and `opena
 
 ## Support files
 
-[`download_static_assets.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/download_static_assets.py) downloads the Swagger UI and ReDoc files used by `self_hosted_docs_app.py`, and the [`dashboard_assets/`](https://github.com/mat81black/fastapi-router-versioning/tree/main/examples/dashboard_assets) folder holds the template and stylesheet of `versions_dashboard_hook_app.py`.
+[`download_static_assets.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/download_static_assets.py) downloads the Swagger UI and ReDoc files used by `self_hosted_docs_app.py`, and the [`dashboard_assets/`](https://github.com/matblack81/fastapi-router-versioning/tree/main/examples/dashboard_assets) folder holds the template and stylesheet of `versions_dashboard_hook_app.py`.

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/how-it-works.md

@@ -22,7 +22,7 @@ Every version mentioned by any route, as `version`, `deprecate_in` or `remove_in
 
 Because the key is the path *and* the method, one method of a route can be replaced while the others carry on, and a version that only removes routes still exists, with no routes at all if nothing else is active.
 
-For [`semver_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/semver_app.py) this gives:
+For [`semver_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/semver_app.py) this gives:
 
 | Version | Routes served |
 |---|---|

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/index.md

@@ -19,7 +19,7 @@ Running multiple API versions side by side usually means duplicating routers, ha
 
 ## What you get
 
-Every version gets its own Swagger UI, ReDoc and `openapi.json`, listing only the routes active in that version. These screenshots come from [`semver_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/semver_app.py), where `/lifecycle` and `/legacy-notice` are deprecated in v2.0, `/newcomer` is added in v2.0, and a dedicated route takes over `POST /settings`.
+Every version gets its own Swagger UI, ReDoc and `openapi.json`, listing only the routes active in that version. These screenshots come from [`semver_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/semver_app.py), where `/lifecycle` and `/legacy-notice` are deprecated in v2.0, `/newcomer` is added in v2.0, and a dedicated route takes over `POST /settings`.
 
 === "Swagger UI, v1.0"
 

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/lifecycle.md

@@ -43,17 +43,32 @@ ever turns deprecation *on* for versions at or after its boundary; it never turn
 
 A route with `methods=["GET", "POST"]` can have just one of its methods taken over by a
 dedicated route in a later version; the other method keeps being served by the original
-route. See [`semver_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/semver_app.py)
+route. See [`semver_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/semver_app.py)
 for a working example.
 
 ## In the generated docs
 
 In each version's Swagger UI and ReDoc, a route in its deprecation window is struck through, a route
-removed from a version is absent, and a route introduced later appears only from that version. This is
-v2.0 of [`semver_app.py`](https://github.com/mat81black/fastapi-router-versioning/blob/main/examples/semver_app.py):
-`/lifecycle` and `/legacy-notice` are deprecated from v2.0, and `/newcomer` is introduced in it.
+removed from a version is absent, and a route introduced later appears only from that version. These are
+v1.0, v2.0 and v3.0 of [`semver_app.py`](https://github.com/matblack81/fastapi-router-versioning/blob/main/examples/semver_app.py):
 
-![Swagger UI of version 2.0, with lifecycle and legacy-notice struck through as deprecated and newcomer added](assets/screenshots/swagger-v2.jpg){ loading=lazy }
+=== "v1.0"
+
+    `/lifecycle` and `/legacy-notice` are active, and `/newcomer` and `/future` don't exist yet.
+
+    ![Swagger UI of version 1.0, with persistent, lifecycle, legacy-notice, settings and items](assets/screenshots/swagger-v1.jpg){ loading=lazy }
+
+=== "v2.0"
+
+    `/lifecycle` and `/legacy-notice` are deprecated from v2.0, and `/newcomer` is introduced in it.
+
+    ![Swagger UI of version 2.0, with lifecycle and legacy-notice struck through as deprecated and newcomer added](assets/screenshots/swagger-v2.jpg){ loading=lazy }
+
+=== "v3.0"
+
+    `/lifecycle` is removed. `/legacy-notice` has no `remove_in`, so it stays, still deprecated, and `/future` is introduced.
+
+    ![Swagger UI of version 3.0, without lifecycle, with legacy-notice still struck through and future added](assets/screenshots/swagger-v3.jpg){ loading=lazy }
 
 ## Deprecation headers
 

fastapi_router_versioning-1.2.1/docs/migrating.md

@@ -0,0 +1,64 @@
+---
+description: Add RouterVersioner to a FastAPI app that already has clients, without breaking the URLs they call.
+---
+
+# Adding it to an existing app
+
+You don't have to rewrite anything to start. A route without `@api_version` is given
+`default_version`, which is v1.0 under SemVer, so the app you have today is already "version 1".
+The steps below keep the unversioned URLs working while your clients move to the versioned ones.
+
+## 1. Versionize what you have
+
+This is an ordinary app, with its router included once:
+
+```python
+--8<-- "docs_src/migration/adopt.py:routes"
+```
+
+Pass the same router to `RouterVersioner` and call `.versionize()`, leaving everything above as it is:
+
+```python
+--8<-- "docs_src/migration/adopt.py:versionize"
+```
+
+Nothing is decorated, so `GET /items` is mounted as `GET /v1_0/items`, with its own docs at `/v1_0/docs`.
+`GET /items` keeps answering too: `app.include_router(router)` is still there, and `RouterVersioner` doesn't touch it.
+
+## 2. Change an endpoint in a new version
+
+Declare the new one at a higher version, next to the old one. The old function stays exactly as it was:
+
+```python
+--8<-- "docs_src/migration/change_endpoint.py:snippet"
+```
+
+| URL | Answered by |
+|-----|-------------|
+| `/items` | the original function, as before |
+| `/v1_0/items` | the original function |
+| `/v2_0/items` | the new function |
+
+!!! note "The unversioned URL does not follow the new version"
+
+    `/items` is served by the router you included yourself, and FastAPI answers with the first route that matches: the original function. It never moves to v2.0, so clients still on it see no change.
+
+The app's own docs, at `/docs`, list the unversioned URL together with every versioned one, while each version's docs list only its own routes:
+
+![Swagger UI at /docs, listing GET /items, GET /v1_0/items and GET /v2_0/items](assets/screenshots/migration-root.jpg){ loading=lazy }
+
+!!! warning "Don't read the unversioned URL from `/docs`"
+
+    FastAPI keeps one operation per path and method in a schema, the last one declared. So `/docs` describes `/items` with the v2.0 function ("Get Items V2" above), while requests to `/items` are answered by the original one. Use `/v1_0/docs` and `/v2_0/docs` as the reference for what each version returns.
+
+## 3. Retire the unversioned URLs
+
+Once your clients call the versioned URLs, remove `app.include_router(router)`. If you still want a URL that always means "the newest", `latest_prefix` adds one:
+
+```python
+--8<-- "docs_src/migration/retire_unversioned.py:snippet"
+```
+
+`/items` now answers 404, and `/latest/items` serves whichever version is highest: see the [latest alias](advanced/latest-alias.md).
+
+Call `.versionize()` once, after every route is declared, as in the [Quick start](quickstart.md). To take a route out of a version later, or to mark it deprecated first, see the [route lifecycle](lifecycle.md).

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/docs/release-notes.md

@@ -2,6 +2,20 @@
 
 ## Latest Changes
 
+## 1.2.1 (2026-10-15)
+
+### Docs
+
+* 🖼️ Adjust logo dimensions in README and script by removing height attribute. PR [#118](https://github.com/matblack81/fastapi-router-versioning/pull/118) by [@matblack81](https://github.com/matblack81).
+* 📝 Add a guide to adopting versioning in an existing app. PR [#116](https://github.com/mat81black/fastapi-router-versioning/pull/116) by [@mat81black](https://github.com/mat81black).
+* 📝 Add v1.0, v2.0 and v3.0 Swagger screenshots to the route lifecycle page. PR [#115](https://github.com/mat81black/fastapi-router-versioning/pull/115) by [@mat81black](https://github.com/mat81black).
+
+### Internal
+
+* 📝 Point documentation links to the new domain. PR [#117](https://github.com/matblack81/fastapi-router-versioning/pull/117) by [@matblack81](https://github.com/matblack81).
+* ⬆ Bump annotated-doc from 0.0.4 to 0.0.5. PR [#114](https://github.com/mat81black/fastapi-router-versioning/pull/114) by [@dependabot[bot]](https://github.com/apps/dependabot).
+* ⬆ Bump the python-packages group with 2 updates. PR [#113](https://github.com/mat81black/fastapi-router-versioning/pull/113) by [@dependabot[bot]](https://github.com/apps/dependabot).
+
 ## 1.2.0 (2026-10-04)
 
 ### Docs

fastapi_router_versioning-1.2.1/docs_src/migration/adopt.py

@@ -0,0 +1,22 @@
+from fastapi import APIRouter, FastAPI
+from fastapi_router_versioning import RouterVersioner, VersionFormat
+
+app = FastAPI()
+router = APIRouter()
+
+
+# --8<-- [start:routes]
+@router.get("/items")
+def get_items():
+    return {"items": ["a", "b"]}
+
+
+app.include_router(router)
+# --8<-- [end:routes]
+
+# --8<-- [start:versionize]
+RouterVersioner(
+    app=app, routers=router,
+    version_format=VersionFormat.SEMVER
+).versionize()
+# --8<-- [end:versionize]

fastapi_router_versioning-1.2.1/docs_src/migration/change_endpoint.py

@@ -0,0 +1,26 @@
+from fastapi import APIRouter, FastAPI
+from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
+
+app = FastAPI()
+router = APIRouter()
+
+
+@router.get("/items")
+def get_items():
+    return {"items": ["a", "b"]}
+
+
+# --8<-- [start:snippet]
+@router.get("/items")
+@api_version((2, 0))
+def get_items_v2():
+    return {"items": ["a", "b", "c"]}
+# --8<-- [end:snippet]
+
+
+app.include_router(router)
+
+RouterVersioner(
+    app=app, routers=router,
+    version_format=VersionFormat.SEMVER
+).versionize()

fastapi_router_versioning-1.2.1/docs_src/migration/retire_unversioned.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, FastAPI
+from fastapi_router_versioning import RouterVersioner, VersionFormat, api_version
+
+app = FastAPI()
+router = APIRouter()
+
+
+@router.get("/items")
+def get_items():
+    return {"items": ["a", "b"]}
+
+
+@router.get("/items")
+@api_version((2, 0))
+def get_items_v2():
+    return {"items": ["a", "b", "c"]}
+
+
+# --8<-- [start:snippet]
+RouterVersioner(
+    app=app, routers=router,
+    version_format=VersionFormat.SEMVER,
+    latest_prefix="/latest",
+).versionize()
+# --8<-- [end:snippet]

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/fastapi_router_versioning/__init__.py

@@ -1,6 +1,6 @@
 from ._versions import VersionFormat, VersionInfo, VersionT, api_version
 from .versioner import RouterVersioner
 
-__version__ = "1.2.0"
+__version__ = "1.2.1"
 
 __all__ = ["RouterVersioner", "api_version", "VersionFormat", "VersionInfo", "VersionT"]

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/mkdocs.yml

@@ -1,9 +1,9 @@
 site_name: FastAPI Router Versioning
 site_description: Router-based API versioning for FastAPI, with per-version docs and a declarative route lifecycle.
-site_url: https://mat81black.github.io/fastapi-router-versioning/
-repo_url: https://github.com/mat81black/fastapi-router-versioning
-repo_name: mat81black/fastapi-router-versioning
-copyright: Copyright &copy; 2026 Matteo Nieddu &middot; <a href="https://github.com/mat81black/fastapi-router-versioning/blob/main/LICENSE">MIT License</a>
+site_url: https://fastapi-router-versioning.matblack81.com/
+repo_url: https://github.com/matblack81/fastapi-router-versioning
+repo_name: matblack81/fastapi-router-versioning
+copyright: Copyright &copy; 2026 Matteo Nieddu &middot; <a href="https://github.com/matblack81/fastapi-router-versioning/blob/main/LICENSE">MIT License</a>
 edit_uri: edit/main/docs/
 
 theme:
@@ -51,13 +51,13 @@ theme:
 extra:
   social:
     - icon: fontawesome/brands/github
-      link: https://github.com/mat81black/fastapi-router-versioning
+      link: https://github.com/matblack81/fastapi-router-versioning
       name: Source code on GitHub
     - icon: fontawesome/brands/python
       link: https://pypi.org/project/fastapi-router-versioning/
       name: fastapi-router-versioning on PyPI
     - icon: fontawesome/solid/bug
-      link: https://github.com/mat81black/fastapi-router-versioning/issues
+      link: https://github.com/matblack81/fastapi-router-versioning/issues
       name: Report an issue
 
 extra_css:
@@ -67,6 +67,7 @@ nav:
   - Home: index.md
   - Guide:
       - Quick start: quickstart.md
+      - Adding it to an existing app: migrating.md
       - Route lifecycle: lifecycle.md
       - How it works: how-it-works.md
       - Advanced options:

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/pyproject.toml

@@ -36,11 +36,11 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://mat81black.github.io/fastapi-router-versioning/"
-Repository = "https://github.com/mat81black/fastapi-router-versioning"
-Issues = "https://github.com/mat81black/fastapi-router-versioning/issues"
-Documentation = "https://mat81black.github.io/fastapi-router-versioning/"
-Changelog = "https://mat81black.github.io/fastapi-router-versioning/release-notes/"
+Homepage = "https://fastapi-router-versioning.matblack81.com/"
+Repository = "https://github.com/matblack81/fastapi-router-versioning"
+Issues = "https://github.com/matblack81/fastapi-router-versioning/issues"
+Documentation = "https://fastapi-router-versioning.matblack81.com/"
+Changelog = "https://fastapi-router-versioning.matblack81.com/release-notes/"
 
 [dependency-groups]
 dev = [

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/scripts/docs_screenshots.py

@@ -46,11 +46,13 @@ class Shot:
 SHOTS = [
     Shot("swagger-v1", "examples/semver_app.py", "/v1_0/docs", "swagger"),
     Shot("swagger-v2", "examples/semver_app.py", "/v2_0/docs", "swagger"),
+    Shot("swagger-v3", "examples/semver_app.py", "/v3_0/docs", "swagger"),
     Shot("redoc-v2", "examples/semver_app.py", "/v2_0/redoc", "redoc"),
     Shot("versions-dashboard", "examples/versions_dashboard_app.py", "/dashboard", "dashboard"),
     Shot("quickstart-semver-v1", "docs_src/quickstart/semver.py", "/v1_0/docs", "swagger"),
     Shot("quickstart-semver-v2", "docs_src/quickstart/semver.py", "/v2_0/docs", "swagger"),
     Shot("quickstart-calver", "docs_src/quickstart/calver.py", "/2025-01-01/docs", "swagger"),
+    Shot("migration-root", "docs_src/migration/change_endpoint.py", "/docs", "swagger"),
     Shot("url-format-v1", "docs_src/advanced/custom_url_format.py", "/v1/docs", "swagger"),
     Shot("url-format-latest", "docs_src/advanced/custom_url_format.py", "/latest/docs", "swagger"),
     Shot("latest-alias", "docs_src/advanced/latest_alias.py", "/latest/docs", "swagger"),

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/scripts/generate_readme.py

@@ -17,12 +17,12 @@ from pathlib import Path
 
 ROOT = Path(__file__).parent.parent
 README = ROOT / "README.md"
-SITE_URL = "https://mat81black.github.io/fastapi-router-versioning/"
-REPO_URL = "https://github.com/mat81black/fastapi-router-versioning"
-ASSETS_URL = "https://raw.githubusercontent.com/mat81black/fastapi-router-versioning/main/docs/assets/images"
+SITE_URL = "https://fastapi-router-versioning.matblack81.com/"
+REPO_URL = "https://github.com/matblack81/fastapi-router-versioning"
+ASSETS_URL = "https://raw.githubusercontent.com/matblack81/fastapi-router-versioning/main/docs/assets/images"
 
 HEADER = f"""<p align="center">
-  <img src="{ASSETS_URL}/logo.svg" alt="FastAPI Router Versioning logo" width="128" height="128">
+  <img src="{ASSETS_URL}/logo.svg" alt="FastAPI Router Versioning logo" width="128">
 </p>
 
 <h1 align="center">
@@ -31,7 +31,7 @@ HEADER = f"""<p align="center">
 
 <p align="center">
   <a href="{REPO_URL}/actions"><img src="{REPO_URL}/workflows/Test/badge.svg" alt="Build Status"></a>
-  <a href="https://codecov.io/github/mat81black/fastapi-router-versioning"><img src="https://codecov.io/github/mat81black/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY" alt="codecov"></a>
+  <a href="https://codecov.io/github/matblack81/fastapi-router-versioning"><img src="https://codecov.io/github/matblack81/fastapi-router-versioning/graph/badge.svg?token=4WQ63Q7ESY" alt="codecov"></a>
   <a href="https://pypi.org/project/fastapi-router-versioning/"><img src="https://img.shields.io/pypi/v/fastapi-router-versioning?color=%2334D058&label=pypi%20package" alt="pypi package"></a>
   <a href="https://pypi.org/project/fastapi-router-versioning/"><img src="https://img.shields.io/pypi/pyversions/fastapi-router-versioning.svg?color=%2334D058" alt="Supported Python versions"></a>
   <a href="{REPO_URL}/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>

{fastapi_router_versioning-1.2.0 → fastapi_router_versioning-1.2.1}/tests/test_docs_src_behavior.py

@@ -176,3 +176,34 @@ def test_route_callbacks_are_carried_into_the_version() -> None:
     client = TestClient(load("advanced/callbacks").app)
 
     assert schema(client, "/v1_0")["paths"]["/v1_0/items"]["post"]["callbacks"]
+
+
+def test_migration_adopt_keeps_the_unversioned_url_and_mounts_v1() -> None:
+    client = TestClient(load("migration/adopt").app)
+
+    assert client.get("/items").json() == {"items": ["a", "b"]}
+    assert client.get("/v1_0/items").json() == {"items": ["a", "b"]}
+    assert client.get("/v1_0/docs").status_code == 200
+    assert client.get("/v2_0/items").status_code == 404
+
+
+def test_migration_unversioned_url_does_not_follow_the_new_version() -> None:
+    client = TestClient(load("migration/change_endpoint").app)
+
+    assert client.get("/items").json() == {"items": ["a", "b"]}
+    assert client.get("/v1_0/items").json() == {"items": ["a", "b"]}
+    assert client.get("/v2_0/items").json() == {"items": ["a", "b", "c"]}
+    # the app's own schema keeps the last operation declared for /items, while requests get the first
+    root_schema = schema(client, "")
+    assert list(root_schema["paths"]) == ["/items", "/v1_0/items", "/v2_0/items"]
+    assert root_schema["paths"]["/items"]["get"]["summary"] == "Get Items V2"
+    assert list(schema(client, "/v1_0")["paths"]) == ["/v1_0/items"]
+    assert list(schema(client, "/v2_0")["paths"]) == ["/v2_0/items"]
+
+
+def test_migration_retiring_the_unversioned_url_leaves_latest() -> None:
+    client = TestClient(load("migration/retire_unversioned").app)
+
+    assert client.get("/items").status_code == 404
+    assert client.get("/v1_0/items").json() == {"items": ["a", "b"]}
+    assert client.get("/latest/items").json() == {"items": ["a", "b", "c"]}