Skip to content

Release Notes

Latest Changes

1.2.1 (2026-10-15)

Docs

  • 🖼️ Adjust logo dimensions in README and script by removing height attribute. PR #118 by @matblack81.
  • 📝 Add a guide to adopting versioning in an existing app. PR #116 by @mat81black.
  • 📝 Add v1.0, v2.0 and v3.0 Swagger screenshots to the route lifecycle page. PR #115 by @mat81black.

Internal

1.2.0 (2026-10-04)

Docs

Internal

1.1.1 (2026-09-22)

Internal

1.1.0 (2026-09-09)

Features

  • ✨ Show each version's migration guide on /versions and the dashboard. PR #101 by @mat81black.
  • ✨ Signal route deprecation to clients with RFC 9745 Deprecation, RFC 8594 Sunset and Link headers. PR #98 by @mat81black.
  • ✨ Add an HTML dashboard listing all active API versions. PR #97 by @mat81black.
  • ✨ Make the /versions discovery endpoint path configurable. PR #95 by @mat81black.

Refactors

  • ♻️ Default versions_route_path and versions_dashboard_path to their paths instead of None. PR #104 by @mat81black.

Docs

  • 💡 Review the comments and docstrings across package, tests and examples. PR #103 by @mat81black.
  • 📝 Complete the README reference and make its wording plainer. PR #100 by @mat81black.
  • 📝 Document the deprecation headers in the README. PR #99 by @mat81black.

Internal

  • ♻️ Split versioner.py into single-responsibility private modules. PR #102 by @mat81black.
  • 🐛 Fix test-redistribute collection error from anyio's deprecated BlockingPortal alias. PR #96 by @mat81black.
  • ⬆ Bump the python-packages group with 4 updates. PR #94 by @dependabot[bot].
  • ⬆ Bump re-actors/alls-green from 1.2.2 to 1.3.0 in the github-actions group. PR #93 by @dependabot[bot].
  • ⬆ Bump pre-commit hooks. PR #92 by @mat81black.
  • ⬆ Bump fastapi from 0.140.0 to 0.141.1. PR #91 by @dependabot[bot].
  • ⬆ Bump the python-packages group with 11 updates. PR #90 by @dependabot[bot].
  • ⬆ Bump the github-actions group with 2 updates. PR #89 by @dependabot[bot].
  • 👷 Replace actions/labeler with Latest Changes App auto-labeling. PR #87 by @mat81black.

1.0.3 (2026-08-13)

Fixes

  • 🐛 Fix tag metadata missing from versioned schemas when tags use an Enum. PR #81 by @mat81black.
  • 🐛 Distinguish an unset webhook_routers from one provided but empty. PR #80 by @mat81black.
  • 🐛 Read route attributes from the merged RouteContext instead of the original route. PR #79 by @mat81black.
  • 🐛 Preserve custom route_class when mounting versioned routes. PR #78 by @mat81black.

Refactors

  • ♻️ Move prefix and /versions bookkeeping off app.state into a private registry. PR #84 by @mat81black.

Internal

  • ♻️ Reorganize versioner tests into docs, lifecycle, webhooks, and errors files. PR #85 by @mat81black.
  • ✅ Cover versionize() on a router with no routes. PR #83 by @mat81black.
  • ✅ Cover default_version type validation on construction. PR #82 by @mat81black.

1.0.2 (2026-08-12)

Internal

  • ✅ Cover examples/ with an import-and-schema smoke test and align their run instructions. PR #76 by @mat81black.
  • ♻️ Standardize examples with a run instruction docstring, drop the main blocks. PR #75 by @mat81black.
  • 👷 Sync CI, pre-commit, and release scripts workflows with the latest template. PR #74 by @mat81black.
  • 🐛 Fix release date defaulting to the date the script was imported. PR #73 by @mat81black.
  • 🐛 Fix partial release state when release notes write fails. PR #72 by @mat81black.
  • 🐛 Reject invalid bump types and cover prepare_release's untested error paths. PR #71 by @mat81black.
  • 🐛 Fix partial release state when release notes update fails. PR #70 by @mat81black.
  • ⬆️ Bump tiangolo/latest-changes to 0.7.1. PR #69 by @mat81black.
  • ✅ Prove PR test changes actually catch a regression before merging. PR #68 by @mat81black.
  • ⬆ Bump fastapi from 0.139.2 to 0.140.0. PR #67 by @dependabot[bot].
  • ⬆ Bump the python-packages group with 5 updates. PR #66 by @dependabot[bot].
  • ⬆ Bump zizmorcore/zizmor-action from 0.6.0 to 0.6.1 in the github-actions group. PR #65 by @dependabot[bot].

1.0.1 (2026-08-01)

Fixes

  • 🐛 Fix missing OpenAPI validation in docs URL checks when versioning is enabled. PR #61 by @mat81black.
  • 🐛 Fix versionize() failures blocking any retry on the same app. PR #58 by @mat81black.
  • 🐛 Fix OpenAPI schema caching to handle /latest alias independently. PR #57 by @mat81black.
  • 🐛 Fix include_version_openapi_route not disabling docs UIs. PR #55 by @mat81black.
  • 🐛 Fix duplicate route registration for multi-method endpoints. PR #54 by @mat81black.
  • 🐛 Fix deprecation never becoming observable when deprecate_in is the only lifecycle change. PR #53 by @mat81black.
  • 🐛 Fix route removal deleting its replacement instead of the removed route. PR #52 by @mat81black.

Refactors

  • ♻️ Refactor _add_versions_route to support multiple version model providers. PR #60 by @mat81black.
  • 🐛 Simplify versionize() error handling and remove rollback logic. PR #59 by @mat81black.

Docs

  • 📝 Update README with examples for permanent deprecation, multi-method takeover, and shared /versions behavior. PR #63 by @mat81black.
  • ♻️ Add permanent deprecation and multi-method takeover examples to semver_app. PR #62 by @mat81black.

1.0.0 (2026-07-28)

🎉 First stable release of fastapi-router-versioning.

0.3.0 (2026-07-28)

Breaking Changes

  • ♻️ Remove built-in validation error override in favor of fastapi-validation-override. PR #46 by @mat81black.

Internal

0.2.7 (2026-07-18)

Internal

  • ⬆ Bump pre-commit hooks. PR #44 by @mat81black.
  • ⬆ Bump the python-packages group across 1 directory with 5 updates. PR #42 by @dependabot[bot].
  • ⬆ Bump the github-actions group across 1 directory with 2 updates. PR #41 by @dependabot[bot].
  • 👷 Replace Dependabot pre-commit ecosystem with custom bump workflow. PR #43 by @mat81black.

0.2.6 (2026-07-11)

Refactors

  • ♻️ Use fastapi-native imports instead of importing from starlette directly. PR #38 by @mat81black.

0.2.5 (2026-07-10)

Fixes

  • 🐛 Fix misleading self-collision error in RouterVersioner prefix claiming. PR #36 by @mat81black.

0.2.4 (2026-07-09)

Internal

  • 🔧 Integrate Codecov for coverage tracking and update README. PR #34 by @mat81black.

0.2.3 (2026-07-09)

Docs

  • 📝 Rewrite README with PyPI-safe links and corrected project metadata. PR #27 by @mat81black.

Internal

  • ⬆ bump the python-packages group with 2 updates. PR #30 by @dependabot[bot].
  • ⬆ bump https://github.com/crate-ci/typos from v1.48.0 to 5.0.7 in the pre-commit group. PR #29 by @dependabot[bot].
  • ⬆ bump dorny/paths-filter from 4.0.1 to 4.0.2 in the github-actions group. PR #31 by @dependabot[bot].
  • ⬆ bump fastapi from 0.138.1 to 0.139.0. PR #32 by @dependabot[bot].
  • 🔧 Overhaul CI/CD workflows for labeling, releases, and coverage tracking. PR #28 by @mat81black.

0.2.2 (2026-07-01)

Fixes

  • 🐛 Fix root OpenAPI schema not reflecting validation_error_code. PR #21 by @mat81black.
  • 🐛 Fix silent conflicts from misconfigured RouterVersioner instances sharing an app. PR #20 by @mat81black.

Internal

  • 👷 Add a regression test for RouterVersioner under a real app.mount() sub-application, and examples/mounted_subapps_app.py demonstrating the same scenario. PR #22 by @mat81black.

Refactors

  • ♻️ Reorder RouterVersioner methods to match their call graph. PR #23 by @mat81black.

0.2.1 (2026-06-26)

Fixes

  • 🐛 Fix api_version signature to enforce deprecate_in and remove_in as keyword-only arguments, aligning the implementation with the documented signature. PR #18 by @mat81black.

0.2.0 (2026-06-26)

Features

  • ✨ Add validation_error_code parameter to RouterVersioner to override the HTTP status code returned for request validation errors (default: 422). The OpenAPI schema is updated automatically to reflect the custom code. PR #16 by @mat81black.
  • ✨ Add handle_validation_exceptions parameter to RouterVersioner: when False, only the OpenAPI schema is updated, leaving the exception handler to the user. PR #16 by @mat81black.

Fixes

  • 🐛 Fix Python 3.14 classifier not actually added to pyproject.toml in 0.1.2. PR #15 by @mat81black.

0.1.2 (2026-06-25)

Internal

  • 👷 Add Python 3.14 classifier to pyproject.toml to align with the versions already covered by CI.

Docs

  • 📝 Update README and pyproject.toml to clarify package description and improve documentation consistency. PR #12 by @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 by @mat81black.
  • ✨ Track which routes belong to each version to invalidate the cache automatically when the route set changes. PR #5 by @mat81black.

Fixes

  • 🐛 Fix WebSocket routes not being handled correctly in versioned_routers when the cache was active. PR #5 by @mat81black.
  • 🐛 Improve OpenAPI schema cache resilience: cache is now safely bypassed on unexpected errors instead of raising. PR #5 by @mat81black.

Internal

  • 👷 Add prepare-release.yml workflow and scripts/prepare_release.py for automated version bumping and release PR creation. PR #6 by @mat81black.
  • 👷 Add changes job to test.yml and test-redistribute.yml to skip CI when no relevant files are modified. PR #10 by @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.