Metadata-Version: 2.4
Name: fastapi-router-variants
Version: 0.2.0
Summary: Path variants, API versioning and per-version OpenAPI documentation for FastAPI routers
Project-URL: Homepage, https://github.com/Toilal/fastapi-router-variants
Project-URL: Repository, https://github.com/Toilal/fastapi-router-variants
Project-URL: Changelog, https://github.com/Toilal/fastapi-router-variants/blob/develop/CHANGELOG.md
Project-URL: Issues, https://github.com/Toilal/fastapi-router-variants/issues
Author-email: Rémi Alvergnat <toilal.dev@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-versioning,fastapi,openapi,routing,versioning
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: inflect
Requires-Dist: openapi-spec-validator
Requires-Dist: typing-extensions
Description-Content-Type: text/markdown

# fastapi-router-variants

[![Latest Version](https://img.shields.io/pypi/v/fastapi-router-variants.svg)](https://pypi.python.org/pypi/fastapi-router-variants)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Toilal/fastapi-router-variants/blob/develop/LICENSE)
[![Build Status](https://img.shields.io/github/actions/workflow/status/Toilal/fastapi-router-variants/ci.yml?branch=develop)](https://github.com/Toilal/fastapi-router-variants/actions/workflows/ci.yml)
[![Codecov](https://img.shields.io/codecov/c/github/Toilal/fastapi-router-variants)](https://codecov.io/gh/Toilal/fastapi-router-variants)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/relekang/python-semantic-release)

Declare a route once and get **path variants**, **API versioning** and
**per-version OpenAPI documentation** for [FastAPI](https://fastapi.tiangolo.com/)
— for free.

`fastapi-router-variants` wraps `APIRouter` with a `RouterWrapper` that expands a
single route declaration into every variant it should serve — multiple paths,
multiple version prefixes (`/v1/...`, `/v2/...`), multiple mount prefixes, with
deprecation handled automatically — then builds a separate OpenAPI schema per
version and mounts Swagger UI / ReDoc / `openapi.json` for each of them.

## Install

```bash
pip install fastapi-router-variants
# or
uv add fastapi-router-variants
```

## Usage

```python
from fastapi import FastAPI

from fastapi_router_variants import RouterDefaults, RouterWrapper


class ApiDefaults(RouterDefaults):
    prefix = "/api"           # mount every route under /api
    version = True            # force versioning on every route
    version_range = (1, 3)    # generate v1, v2, v3
    version_default = 3       # the version served on unversioned doc URLs


RouterWrapper.defaults = ApiDefaults()

router = RouterWrapper()


@router.get("/users/{user_id}")
def get_user(user_id: int) -> dict[str, int]:
    return {"id": user_id}


app = FastAPI()
app.include_router(router.base)
```

The single `get` declaration above registers `GET /api/v1/users/{user_id}`,
`GET /api/v2/users/{user_id}` and `GET /api/v3/users/{user_id}`.

Path variants and flavors, versioning helpers, routing specs, per-version
OpenAPI documents, custom categories and HTTP-error auto-documentation are
all covered in the documentation.

## Documentation

Full documentation is available at
[toilal.github.io/fastapi-router-variants](https://toilal.github.io/fastapi-router-variants/).
A preview of the in-progress `develop` branch is published at
[toilal.github.io/fastapi-router-variants/dev](https://toilal.github.io/fastapi-router-variants/dev/).

## Requirements

- Python ≥ 3.12
- FastAPI ≥ 0.115

## License

[MIT](./LICENSE) © Rémi Alvergnat


# CHANGELOG

<!-- version list -->

## v0.2.0 (2026-07-05)

### Features

- Support Python 3.11 ([#13](https://github.com/Toilal/fastapi-router-variants/pull/13),
  [`ab9301d`](https://github.com/Toilal/fastapi-router-variants/commit/ab9301dae07480e1d8b6ae45af04e230241c65e8))


## v0.1.0 (2026-07-05)

- Initial Release

Changelog entries are generated automatically by
[python-semantic-release](https://python-semantic-release.readthedocs.io/) from
[Conventional Commits](https://www.conventionalcommits.org/) on release.
