# Versioned FastAPI
Versioned FastAPI simplifies the versioning of [FastAPI](https://github.com/tiangolo/fastapi) web applications.
This package is mainly designed for versioning of single endpoints.
It can also be used for versioning of entire APIs,
but then other packages like [FastAPI Versionizer](https://github.com/alexschimpf/fastapi-versionizer) might be a better
fit
if you are not interested in the modifications of the swagger docs.
Modifies the swagger documentation by adding a dropdown menu for easy switching between different versions.
## Credit
This project is inspired by [FastAPI Versionizer](https://github.com/alexschimpf/fastapi-versionizer) but is mainly
designed for versioning of single endpoints.
## Installation
```commandline
pip install versioned-fastapi
```
## Usage
> For more examples see the [examples](https://github.com/mivoelcker/versioned-fastapi/blob/main/examples) directory.
A minimalistic example of how to use Versioned FastAPI:
```python
from typing import Dict, Union
from fastapi import FastAPI, APIRouter, HTTPException
from pydantic import BaseModel
from versioned_fastapi import version, FastApiVersioner
# Versioned models
class Item(BaseModel):
id: int
name: str
class ItemV2(BaseModel):
id: int
name: str
description: str
# Example db
db: Dict[int, Union[Item, ItemV2]] = {}
# Create the FastAPI app ...
app = FastAPI(
title="Versioned FastAPI",
description="Simple example of Versioned FastAPI.",
)
# ... and routers as normal
items_router = APIRouter(
prefix="/items",
tags=["Items"]
)
# Use the @version annotation to add a version
# This endpoint will be available at "/v1/items"
@version(1)
@items_router.post("", status_code=201, deprecated=True)
async def create_item(item: Item):
db[item.id] = item
return item
# This endpoint will be available at "/v1/items"
@version(2)
@items_router.post("", status_code=201)
async def create_item_v2(item: ItemV2) -> ItemV2:
db[item.id] = item
return item
# This endpoint will be available at "/v1/items/{item_id}"
@version(1)
@items_router.get("/{item_id}")
async def get_item(item_id: int) -> Union[Item, ItemV2]:
if item_id in db:
return db[item_id]
raise HTTPException(status_code=404, detail="Item not found")
app.include_router(items_router)
# Version your app
# It will add version prefixes and customize the swagger docs
versions = FastApiVersioner(app).version_fastapi()
```
In addition to the manipulation of the annotated routes, new and versioned openapi endpoints will be created.
To show the new openapi definitions the swagger ui will be customized.
You can switch between the versions via a dropdown menu.
The following endpoints will be available:
- **POST /v1/items**
- **POST /v2/items**
- **GET /v1/items/{items_id}**
- **GET /openapi.json** The openapi definition containing all routes of all versions
- **GET /v1/openapi.json** The openapi definition containing all routes of version 1
- **GET /v2/openapi.json** The openapi definition containing all routes of version 2
- **GET /docs** The customized Swagger documentation
## Customization
To customize the outcome you can use the init parameter of the FastApiVersioner class:
- **app**: The fastapi app to version, required.
- **default_version**: Default version to use if a route is not annotated with @version.
- **prefix_format**: Defines the format of the path prefix, should contain "{version}".
- **include_all_routes**: If True, the main openapi route without version prefix will be included in swagger as "All
Routes".
- **primary_swagger_version**: The version to be displayed when the swagger ui loads. If None "All Routes" or the first
version will be selected.
For further customization you can set some class parameter (see [customization example](https://github.com/mivoelcker/versioned-fastapi/blob/main/examples/customization.py)) or
inherit the FastApiVersioner class.
But keep in mind that all protected methods and attributed might change in the future.
- **title_format**: Defines the format of the swagger title, can contain "{title}" and "{version}".
- **description_format**: Defines the format of the swagger description, can contain "{description}" and "{version}" and
supports markdown.
- **summary_format**: Defines the format of the swagger summary, can contain "{summary}" and "{version}". Available
since OpenAPI 3.1.0, FastAPI 0.99.0.
- **swagger_js_urls**: The URLs to use to load the Swagger UI JavaScript.
- **swagger_css_urls**: The URLs to use to load Swagger UI CSS. Leave None to use FastAPIs default.
- **swagger_favicon_url**: The URL of the favicon to use. Leave None to use FastAPIs default.
## Keep in mind
- Currently, the versioning of websockets is not supported, but this might be added in the future
- The Redoc documentation will not be modified and will always show all routes of all versions
- If you customized your swagger docs, this might conflict with the docs route created by this package
- If you customized the openapi endpoint, this will not affect the versioned endpoints
Raw data
{
"_id": null,
"home_page": "",
"name": "versioned-fastapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "fastapi,version,versioned-fastapi,versioning",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/50/b1/22930c65ebe723c900468fceb124d8ca9a4dfbda9bfc1d1b34f5b1c8e958/versioned_fastapi-1.0.0.tar.gz",
"platform": null,
"description": "# Versioned FastAPI\n\nVersioned FastAPI simplifies the versioning of [FastAPI](https://github.com/tiangolo/fastapi) web applications.\nThis package is mainly designed for versioning of single endpoints.\nIt can also be used for versioning of entire APIs,\nbut then other packages like [FastAPI Versionizer](https://github.com/alexschimpf/fastapi-versionizer) might be a better\nfit\nif you are not interested in the modifications of the swagger docs.\n\nModifies the swagger documentation by adding a dropdown menu for easy switching between different versions.\n\n## Credit\n\nThis project is inspired by [FastAPI Versionizer](https://github.com/alexschimpf/fastapi-versionizer) but is mainly\ndesigned for versioning of single endpoints.\n\n## Installation\n\n```commandline\npip install versioned-fastapi\n```\n\n## Usage\n> For more examples see the [examples](https://github.com/mivoelcker/versioned-fastapi/blob/main/examples) directory.\n\nA minimalistic example of how to use Versioned FastAPI:\n\n```python\nfrom typing import Dict, Union\nfrom fastapi import FastAPI, APIRouter, HTTPException\nfrom pydantic import BaseModel\nfrom versioned_fastapi import version, FastApiVersioner\n\n\n# Versioned models\nclass Item(BaseModel):\n id: int\n name: str\n\n\nclass ItemV2(BaseModel):\n id: int\n name: str\n description: str\n\n\n# Example db\ndb: Dict[int, Union[Item, ItemV2]] = {}\n\n# Create the FastAPI app ...\napp = FastAPI(\n title=\"Versioned FastAPI\",\n description=\"Simple example of Versioned FastAPI.\",\n)\n\n# ... and routers as normal\nitems_router = APIRouter(\n prefix=\"/items\",\n tags=[\"Items\"]\n)\n\n\n# Use the @version annotation to add a version\n# This endpoint will be available at \"/v1/items\"\n@version(1)\n@items_router.post(\"\", status_code=201, deprecated=True)\nasync def create_item(item: Item):\n db[item.id] = item\n return item\n\n\n# This endpoint will be available at \"/v1/items\"\n@version(2)\n@items_router.post(\"\", status_code=201)\nasync def create_item_v2(item: ItemV2) -> ItemV2:\n db[item.id] = item\n return item\n\n\n# This endpoint will be available at \"/v1/items/{item_id}\"\n@version(1)\n@items_router.get(\"/{item_id}\")\nasync def get_item(item_id: int) -> Union[Item, ItemV2]:\n if item_id in db:\n return db[item_id]\n raise HTTPException(status_code=404, detail=\"Item not found\")\n\n\napp.include_router(items_router)\n\n# Version your app\n# It will add version prefixes and customize the swagger docs\nversions = FastApiVersioner(app).version_fastapi()\n```\n\nIn addition to the manipulation of the annotated routes, new and versioned openapi endpoints will be created.\nTo show the new openapi definitions the swagger ui will be customized.\nYou can switch between the versions via a dropdown menu.\n\n\n\nThe following endpoints will be available:\n\n- **POST /v1/items**\n- **POST /v2/items**\n- **GET /v1/items/{items_id}**\n- **GET /openapi.json** The openapi definition containing all routes of all versions\n- **GET /v1/openapi.json** The openapi definition containing all routes of version 1\n- **GET /v2/openapi.json** The openapi definition containing all routes of version 2\n- **GET /docs** The customized Swagger documentation\n\n## Customization\n\nTo customize the outcome you can use the init parameter of the FastApiVersioner class:\n\n- **app**: The fastapi app to version, required.\n- **default_version**: Default version to use if a route is not annotated with @version.\n- **prefix_format**: Defines the format of the path prefix, should contain \"{version}\".\n- **include_all_routes**: If True, the main openapi route without version prefix will be included in swagger as \"All\n Routes\".\n- **primary_swagger_version**: The version to be displayed when the swagger ui loads. If None \"All Routes\" or the first\n version will be selected.\n\nFor further customization you can set some class parameter (see [customization example](https://github.com/mivoelcker/versioned-fastapi/blob/main/examples/customization.py)) or\ninherit the FastApiVersioner class.\nBut keep in mind that all protected methods and attributed might change in the future.\n\n- **title_format**: Defines the format of the swagger title, can contain \"{title}\" and \"{version}\".\n- **description_format**: Defines the format of the swagger description, can contain \"{description}\" and \"{version}\" and\n supports markdown.\n- **summary_format**: Defines the format of the swagger summary, can contain \"{summary}\" and \"{version}\". Available\n since OpenAPI 3.1.0, FastAPI 0.99.0.\n- **swagger_js_urls**: The URLs to use to load the Swagger UI JavaScript.\n- **swagger_css_urls**: The URLs to use to load Swagger UI CSS. Leave None to use FastAPIs default.\n- **swagger_favicon_url**: The URL of the favicon to use. Leave None to use FastAPIs default.\n\n## Keep in mind\n\n- Currently, the versioning of websockets is not supported, but this might be added in the future\n- The Redoc documentation will not be modified and will always show all routes of all versions\n- If you customized your swagger docs, this might conflict with the docs route created by this package\n- If you customized the openapi endpoint, this will not affect the versioned endpoints\n",
"bugtrack_url": null,
"license": "",
"summary": "Simple versioning of FastAPI web applications",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/mivoelcker/versioned-fastapi#readme",
"Source": "https://github.com/mivoelcker/versioned-fastapi"
},
"split_keywords": [
"fastapi",
"version",
"versioned-fastapi",
"versioning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25c38106b1480c66ce561e75a8292cdd88b175de7f4c345cce0362fa8d6fe2d7",
"md5": "042cb1dec5abda1885ecb372e51e6d6d",
"sha256": "a640b0d517c444655737ac0941a28d03cdb7eef3a73695e23e55ee1fc9000812"
},
"downloads": -1,
"filename": "versioned_fastapi-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "042cb1dec5abda1885ecb372e51e6d6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7215,
"upload_time": "2024-01-27T16:45:02",
"upload_time_iso_8601": "2024-01-27T16:45:02.709628Z",
"url": "https://files.pythonhosted.org/packages/25/c3/8106b1480c66ce561e75a8292cdd88b175de7f4c345cce0362fa8d6fe2d7/versioned_fastapi-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50b122930c65ebe723c900468fceb124d8ca9a4dfbda9bfc1d1b34f5b1c8e958",
"md5": "0fb33d1178f69a1fddb7de578e927759",
"sha256": "7bdbc1300192ef1367d2364b424ee056f00b4eac82a030fece012ce593de6678"
},
"downloads": -1,
"filename": "versioned_fastapi-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0fb33d1178f69a1fddb7de578e927759",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 38930,
"upload_time": "2024-01-27T16:45:04",
"upload_time_iso_8601": "2024-01-27T16:45:04.277700Z",
"url": "https://files.pythonhosted.org/packages/50/b1/22930c65ebe723c900468fceb124d8ca9a4dfbda9bfc1d1b34f5b1c8e958/versioned_fastapi-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-27 16:45:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mivoelcker",
"github_project": "versioned-fastapi#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "versioned-fastapi"
}
JSON
