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

{fastapi_router_versioning-1.1.0 → fastapi_router_versioning-1.2.0}/.github/latest-changes.yml

@@ -1,7 +1,11 @@
 auto-labels:
   docs:
     - README.md
-    - release-notes.md
+    - docs/**
+    - docs_src/**
+    - examples/**
+    - mkdocs.yml
+    - overrides/**
   internal:
     - .github/**
     - scripts/**

fastapi_router_versioning-1.2.0/.github/workflows/build-docs.yml

@@ -0,0 +1,97 @@
+name: Build Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions: {}
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    # Required permissions
+    permissions:
+      pull-requests: read
+    timeout-minutes: 5
+    # Set job outputs to values from filter step
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 #sync-pin:checkout-6
+        with:
+          persist-credentials: false
+      # For pull requests it's not necessary to checkout the code but for the main branch it is
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.2 #sync-pin:paths-filter-2
+        id: filter
+        with:
+          filters: |
+            docs:
+              - .github/workflows/build-docs.yml
+              - .github/workflows/deploy-docs.yml
+              - docs/**
+              - docs_src/**
+              - examples/**
+              - fastapi_router_versioning/**
+              - mkdocs.yml
+              - overrides/**
+              - scripts/docs-build.sh
+              - pyproject.toml
+              - uv.lock
+
+  build-docs:
+    needs:
+      - changes
+    if: needs.changes.outputs.docs == 'true'
+    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 #sync-pin:checkout-7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 #sync-pin:setup-python-3
+        with:
+          python-version-file: .python-version
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv-4
+        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"
+          # Zensical's own docs advise against caching its build output on CI for now.
+          enable-cache: false
+
+      - name: Install Dependencies
+        run: uv sync --locked --no-dev --group docs
+
+      - name: Build docs
+        run: uv run --no-sync bash scripts/docs-build.sh
+
+      # The site is deployed by Deploy Docs, which runs once this workflow has finished
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 #sync-pin:upload-artifact-3
+        with:
+          name: docs-site
+          path: ./site
+
+  # https://github.com/marketplace/actions/alls-green#why
+  docs-alls-green:  # This job does nothing and is only used for the branch protection
+    if: always()
+    needs:
+      - changes
+      - build-docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.2.2 #sync-pin:alls-green-2
+        with:
+          jobs: ${{ toJSON(needs) }}
+          allowed-skips: build-docs

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

@@ -25,7 +25,7 @@ jobs:
         with:
           python-version-file: ".python-version"
       - name: Setup uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv
         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-1.1.0 → fastapi_router_versioning-1.2.0}/.github/workflows/create-draft-release.yml

@@ -16,7 +16,7 @@ jobs:
       contents: write
     env:
       PREPARE_RELEASE_VERSION_FILE: fastapi_router_versioning/__init__.py
-      PREPARE_RELEASE_RELEASE_NOTES_FILE: release-notes.md
+      PREPARE_RELEASE_RELEASE_NOTES_FILE: docs/release-notes.md
     steps:
       - name: Dump GitHub context
         env:
@@ -31,7 +31,7 @@ jobs:
         with:
           python-version-file: ".python-version"
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv
         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-1.2.0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,58 @@
+name: Deploy Docs
+
+on:
+  workflow_run: # zizmor: ignore[dangerous-triggers] -- only a successful push to main of this repository is deployed; pull request builds never are
+    workflows:
+      - Build Docs
+    types:
+      - completed
+
+permissions: {}
+
+jobs:
+  deploy-docs:
+    if: >-
+      github.event.workflow_run.conclusion == 'success'
+      && github.event.workflow_run.head_branch == 'main'
+      && github.event.workflow_run.head_repository.full_name == github.repository
+      && github.event.workflow_run.event == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read # download the artifact of the Build Docs run
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    timeout-minutes: 10
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - name: Clean site
+        run: |
+          rm -rf ./site
+          mkdir ./site
+      # Build Docs is skipped when nothing that goes into the site changed: it uploads no artifact,
+      # the download below finds nothing, and the steps that need ./site/ are skipped
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 #sync-pin:download-artifact-2
+        with:
+          path: ./site/
+          pattern: docs-site
+          merge-multiple: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 #sync-pin:upload-pages-artifact
+        # hashFiles returns an empty string if there are no files
+        if: hashFiles('./site/*')
+        with:
+          path: site
+      - name: Deploy to GitHub Pages
+        # hashFiles returns an empty string if there are no files
+        if: hashFiles('./site/*')
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 #sync-pin:deploy-pages

{fastapi_router_versioning-1.1.0 → fastapi_router_versioning-1.2.0}/.github/workflows/pre-commit.yml

@@ -30,7 +30,7 @@ jobs:
           python-version-file: ".python-version"
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv
         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-1.1.0 → fastapi_router_versioning-1.2.0}/.github/workflows/prepare-release.yml

@@ -28,7 +28,7 @@ jobs:
       pull-requests: write
     env:
       PREPARE_RELEASE_VERSION_FILE: fastapi_router_versioning/__init__.py
-      PREPARE_RELEASE_RELEASE_NOTES_FILE: release-notes.md
+      PREPARE_RELEASE_RELEASE_NOTES_FILE: docs/release-notes.md
     steps:
       - name: Dump GitHub context
         env:
@@ -42,7 +42,7 @@ jobs:
         with:
           python-version-file: ".python-version"
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv
         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-1.1.0 → fastapi_router_versioning-1.2.0}/.github/workflows/publish.yml

@@ -28,7 +28,7 @@ jobs:
         with:
           python-version-file: ".python-version"
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv
         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-1.1.0 → fastapi_router_versioning-1.2.0}/.github/workflows/test.yml

@@ -35,6 +35,7 @@ jobs:
           filters: |
             src:
               - .github/workflows/test.yml
+              - docs_src/**
               - examples/**
               - fastapi_router_versioning/**
               - scripts/**
@@ -80,7 +81,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv
         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
@@ -168,7 +169,7 @@ jobs:
 
       - name: Setup uv
         if: steps.changed-tests.outputs.found == 'true'
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv-2
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv-2
         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
@@ -210,7 +211,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v9.0.0 #sync-pin:setup-uv-3
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v9.0.0 #sync-pin:setup-uv-3
         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
@@ -243,7 +244,7 @@ jobs:
           include-hidden-files: true
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0 #sync-pin:codecov-action
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.0.0 #sync-pin:codecov-action
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage.xml

{fastapi_router_versioning-1.1.0 → fastapi_router_versioning-1.2.0}/.github/workflows/zizmor.yml

@@ -22,4 +22,4 @@ jobs:
         with:
           persist-credentials: false
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054 # v0.6.2 #sync-pin:zizmor-action
+        uses: zizmorcore/zizmor-action@cc914d7f3750a2d13d75c7f184a1060aa0e9d482 # v0.6.2 #sync-pin:zizmor-action

{fastapi_router_versioning-1.1.0 → fastapi_router_versioning-1.2.0}/.gitignore

@@ -10,6 +10,10 @@ __pycache__/
 build/
 dist/
 
+# Docs
+site/
+.cache/
+
 # Coverage
 .coverage
 coverage/

{fastapi_router_versioning-1.1.0 → fastapi_router_versioning-1.2.0}/.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/crate-ci/typos
-    rev: 8a48f81b6c64dcfea44b3633223084c4be58ac5f # frozen: v1.49.0
+    rev: 53821664afd79bb88fcdd22fdc2f49d8d3f6cac9 # frozen: v1
     hooks:
       - id: typos
         args: [ --force-exclude ]
@@ -50,6 +50,14 @@ repos:
         language: unsupported
         pass_filenames: false
 
+      - id: generate-readme
+        name: generate README.md from the docs
+        entry: uv run python scripts/generate_readme.py
+        language: unsupported
+        files: ^(docs/index\.md|docs/quickstart\.md|docs_src/quickstart/semver\.py|scripts/generate_readme\.py)$
+        require_serial: true
+        pass_filenames: false
+
       - id: zizmor
         name: zizmor
         language: python

fastapi_router_versioning-1.2.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: fastapi-router-versioning
+Version: 1.2.0
+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/
+Author-email: Matteo Nieddu <mat81black@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: annotated-doc>=0.0.2
+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">
+</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">
+</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://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>
+</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/
+
+---
+
+## Features
+
+- **SemVer and CalVer**: version routes with `(major, minor)` tuples, or with arbitrary sortable strings
+- **Per-version docs**: isolated Swagger UI, ReDoc, and `openapi.json` for every active version
+- **Declarative lifecycle**: mark a route's introduction, deprecation, and removal with one decorator
+- **Deprecation headers**: opt-in `Deprecation`, `Sunset` and `Link` response headers on routes in their deprecation window
+- **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
+- **Route composition support**: works across nested routers, WebSockets, `Depends`, and OpenAPI Callbacks
+
+---
+
+## Requirements
+
+- Python ≥ 3.10
+- FastAPI ≥ 0.120.0, except `0.137.0` and `0.137.1`
+
+> **Why two FastAPI versions are excluded**
+>
+> `0.137.0` and `0.137.1` shipped a routing internals rewrite before `iter_route_contexts()` landed in `0.137.2`, which this package relies on. Supporting that narrow gap would have meant a third compatibility code path instead of the two the package actually needs.
+
+---
+
+## Installation
+
+```bash
+pip install fastapi-router-versioning
+# or
+uv add fastapi-router-versioning
+```
+
+---
+
+## Quick start
+
+`RouterVersioner` is not a request-time dependency; there's no `Depends()` involved. It's a
+one-time setup step: you build it, then call `.versionize()` once, and it reads the routers
+you gave it and mounts one copy per version. Attach `@api_version` to every route **before**
+calling `.versionize()`, since that call is what reads the router and wires everything up;
+routes added to the router afterward are never picked up.
+
+```python
+from fastapi import APIRouter, FastAPI
+from fastapi_router_versioning import (
+    RouterVersioner, VersionFormat, api_version,
+)
+
+app = FastAPI()
+router = APIRouter()
+
+
+@router.get("/items")
+@api_version((1, 0))
+def get_items_v1():
+    return {"version": "1.0", "items": ["a", "b"]}
+
+
+@router.get("/items")
+@api_version((2, 0))
+def get_items_v2():
+    return {"version": "2.0", "items": ["a", "b", "c"]}
+
+
+RouterVersioner(
+    app=app, routers=router,
+    version_format=VersionFormat.SEMVER
+).versionize()
+```
+
+CalVer, the route lifecycle, the parameter reference and the advanced options are in the [documentation](https://mat81black.github.io/fastapi-router-versioning/).
+
+---
+
+## Release Notes
+
+[RELEASE_NOTES](https://github.com/mat81black/fastapi-router-versioning/blob/main/docs/release-notes.md)
+
+---
+
+## License
+
+[MIT](https://github.com/mat81black/fastapi-router-versioning/blob/main/LICENSE)

fastapi_router_versioning-1.2.0/README.md

@@ -0,0 +1,105 @@
+<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">
+</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">
+</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://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>
+</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/
+
+---
+
+## Features
+
+- **SemVer and CalVer**: version routes with `(major, minor)` tuples, or with arbitrary sortable strings
+- **Per-version docs**: isolated Swagger UI, ReDoc, and `openapi.json` for every active version
+- **Declarative lifecycle**: mark a route's introduction, deprecation, and removal with one decorator
+- **Deprecation headers**: opt-in `Deprecation`, `Sunset` and `Link` response headers on routes in their deprecation window
+- **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
+- **Route composition support**: works across nested routers, WebSockets, `Depends`, and OpenAPI Callbacks
+
+---
+
+## Requirements
+
+- Python ≥ 3.10
+- FastAPI ≥ 0.120.0, except `0.137.0` and `0.137.1`
+
+> **Why two FastAPI versions are excluded**
+>
+> `0.137.0` and `0.137.1` shipped a routing internals rewrite before `iter_route_contexts()` landed in `0.137.2`, which this package relies on. Supporting that narrow gap would have meant a third compatibility code path instead of the two the package actually needs.
+
+---
+
+## Installation
+
+```bash
+pip install fastapi-router-versioning
+# or
+uv add fastapi-router-versioning
+```
+
+---
+
+## Quick start
+
+`RouterVersioner` is not a request-time dependency; there's no `Depends()` involved. It's a
+one-time setup step: you build it, then call `.versionize()` once, and it reads the routers
+you gave it and mounts one copy per version. Attach `@api_version` to every route **before**
+calling `.versionize()`, since that call is what reads the router and wires everything up;
+routes added to the router afterward are never picked up.
+
+```python
+from fastapi import APIRouter, FastAPI
+from fastapi_router_versioning import (
+    RouterVersioner, VersionFormat, api_version,
+)
+
+app = FastAPI()
+router = APIRouter()
+
+
+@router.get("/items")
+@api_version((1, 0))
+def get_items_v1():
+    return {"version": "1.0", "items": ["a", "b"]}
+
+
+@router.get("/items")
+@api_version((2, 0))
+def get_items_v2():
+    return {"version": "2.0", "items": ["a", "b", "c"]}
+
+
+RouterVersioner(
+    app=app, routers=router,
+    version_format=VersionFormat.SEMVER
+).versionize()
+```
+
+CalVer, the route lifecycle, the parameter reference and the advanced options are in the [documentation](https://mat81black.github.io/fastapi-router-versioning/).
+
+---
+
+## Release Notes
+
+[RELEASE_NOTES](https://github.com/mat81black/fastapi-router-versioning/blob/main/docs/release-notes.md)
+
+---
+
+## License
+
+[MIT](https://github.com/mat81black/fastapi-router-versioning/blob/main/LICENSE)

fastapi_router_versioning-1.2.0/docs/advanced/callback-hook.md

@@ -0,0 +1,18 @@
+---
+description: Run a function once for each versioned router before it is mounted.
+---
+
+# Callback hook
+
+`callback` runs for every versioned router, the `latest_prefix` alias included, right before
+`RouterVersioner` includes it in the app, handy for logging every mount point or wiring metrics:
+
+```python
+--8<-- "docs_src/advanced/callback_hook.py:snippet"
+```
+
+If `versionize()` raises, don't catch the exception and retry. Errors found while the versions
+are built, such as a callback that throws or two versions that resolve to the same prefix, are
+raised before anything is added to the app, but the routers are then included one after another,
+and this package makes no attempt to undo a partial inclusion. `versionize()` normally runs at
+startup, so the app fails to start; fix the underlying issue and start it again.

fastapi_router_versioning-1.2.0/docs/advanced/callbacks-and-webhooks.md

@@ -0,0 +1,33 @@
+---
+description: Version OpenAPI webhooks and carry route callbacks into every version.
+---
+
+# OpenAPI callbacks and webhooks
+
+Route-level **Callbacks** need no special handling: a `callbacks=[...]` argument on a route
+is carried over to every versioned copy of it automatically:
+
+```python
+--8<-- "docs_src/advanced/callbacks.py:snippet"
+```
+
+**Webhooks** (`app.webhooks`) are visible in every version's schema by default. Pass
+`webhook_routers` to version them the same way as regular routes, with `@api_version` on
+each definition:
+
+```python
+--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`):
+
+=== "v1.0"
+
+    ![Swagger UI of version 1.0, with a Webhooks section listing order-created and payment-received](../assets/screenshots/webhooks-v1.jpg){ loading=lazy }
+
+=== "v2.0"
+
+    ![Swagger UI of version 2.0, with a Webhooks section listing only order-created](../assets/screenshots/webhooks-v2.jpg){ loading=lazy }
+
+A webhook version only becomes visible once a route version reaches that same prefix, since
+both follow the same `remove_in` lifecycle.

fastapi_router_versioning-1.2.0/docs/advanced/custom-url-format.md

@@ -0,0 +1,25 @@
+---
+description: Change how a version appears in URL prefixes and in the Swagger and ReDoc titles.
+---
+
+# Custom URL format
+
+`prefix_format` and `semantic_version_format` control how a version renders in URLs and in
+doc titles, independently of how it's expressed in `@api_version`. A common use is dropping
+the minor number from the URL while still tracking it internally:
+
+```python
+--8<-- "docs_src/advanced/custom_url_format.py:snippet"
+```
+
+The routes are mounted under `/v1`, `/v2` and `/latest`, and the Swagger titles read `v1` and `v2` instead of `v1.0` and `v2.0`. Here are the docs at `/v1/docs` and at `/latest/docs`, which serves the newest version:
+
+=== "/v1/docs"
+
+    ![Swagger UI at /v1/docs, titled v1 and listing GET /v1/items](../assets/screenshots/url-format-v1.jpg){ loading=lazy }
+
+=== "/latest/docs"
+
+    ![Swagger UI at /latest/docs, titled v2 and listing GET /latest/items](../assets/screenshots/url-format-latest.jpg){ loading=lazy }
+
+Routes are still decorated with `(major, minor)` tuples; only their URL and label change.