API versionizer for FastAPI web applications
Project description
FastAPI Versionizer
Credit
This was inspired by fastapi_versioning.
This project fixes some of the issues with fastapi_versioning
and adds some additional features.
Installation
pip install fastapi-versionizer
Examples
You can find examples in the examples directory.
Summary
FastAPI Versionizer makes API versioning easy.
Here's an example:
from typing import List
from fastapi import FastAPI, APIRouter
from pydantic import BaseModel
from fastapi_versionizer.versionizer import Versionizer, api_version
class User(BaseModel):
id: int
name: str
class UserV2(BaseModel):
id: int
name: str
age: int
db = {
'users': {}
}
app = FastAPI(
title='test',
redoc_url=None
)
users_router = APIRouter(
prefix='/users',
tags=['Users']
)
@app.get('/status', tags=['Status'])
def get_status() -> str:
return 'Ok'
@api_version(1)
@users_router.get('', deprecated=True)
def get_users() -> List[User]:
return list(user for user in db['users'].values() if isinstance(user, User))
@api_version(1)
@users_router.post('', deprecated=True)
def create_user(user: User) -> User:
db['users'][user.id] = user
return user
@api_version(2)
@users_router.get('')
def get_users_v2() -> List[UserV2]:
return list(user for user in db['users'].values() if isinstance(user, UserV2))
@api_version(2)
@users_router.post('')
def create_user_v2(user: UserV2) -> UserV2:
db['users'][user.id] = user
return user
app.include_router(users_router)
app, versions = Versionizer(
app=app,
prefix_format='/v{major}',
semantic_version_format='{major}',
latest_prefix='/latest',
sort_routes=True
).versionize()
This will generate the following endpoints:
- GET /openapi.json
- GET /docs
- GET /v1/openapi.json
- GET /v1/docs
- GET /v1/status
- GET /v1/users
- POST /v1/users
- GET /v2/openapi.json
- GET /v2/docs
- GET /v2/status
- GET /v2/users
- POST /v2/users
- GET /latest/openapi.json
- GET /latest/docs
- GET /latest/status
- GET /latest/users
- POST /latest/users
Details
FastAPI Versionizer works by creating a new FastAPI app with versioned routes and proper docs pages.
Routes are annotated with version information, using the @api_version
decorator.
Using this decorator, you can specify the version (major and/or minor) that the route was introduced.
You can also specify the first version when the route should be considered deprecated or even removed.
Each new version will include all routes from previous versions that have not been overridden or marked for removal.
An APIRouter will be created for each version, with the URL prefix defined by the prefix_format
parameter described below,
Parameters
- app
- The FastAPI you want to version
- prefix_format
- Used to build the version path prefix for routes.
- It should contain either "{major}" or "{minor}" or both.
- Examples: "/v{major}", "/v{major}_{minor}"
- semantic_version_format
- Used to build the semantic version, which is shown in docs.
- Examples: "{major}", "{major}.{minor}"
- default_version
- Default version used if a route is not annotated with @api_version.
- latest_prefix
- If this is given, the routes in your latest version will be a given a separate prefix alias.
- For example, if latest_prefix='latest', latest version is 1, and you have routes: "GET /v1/a" and "POST /v1/b", then "GET /latest/a" and "POST /latest/b" will also be added.
- include_main_docs
- If True, docs page(s) will be created at the root, with all versioned routes included
- include_main_openapi_route
- If True, an OpenAPI route will be created at the root, with all versioned routes included
- include_version_docs
- If True, docs page(s) will be created for each version
- include_version_openapi_route
- If True, an OpenAPI route will be created for each version
- include_versions_route
- If True, a "GET /versions" route will be added, which includes information about all API versions
- sort_routes
- If True, all routes will be naturally sorted by path within each version.
- If you have included the main docs page, the routes are sorted within each version, and versions are sorted from earliest to latest. If you have added a "latest" alias, its routes will be listed last.
- callback
- A function that is called each time a version router is created and all its routes have been added.
- It is called before the router has been added to the root FastAPI app.
- This function should not return anything and has the following parameters:
- Version router
- Version (in tuple form)
- Version path prefix
Docs Customization
- There are various parameters mentioned above for controlling which docs page are generated.
- The swagger and redoc URL paths can be controlled by setting your FastAPI app's
docs_url
andredoc_url
.- If these are set to None, docs pages will not be generated.
- Swagger UI parameters can be controlled by setting your FastAPI app's
swagger_ui_parameters
- If you want to customize your docs beyond what FastAPI Versionizer can handle, you can do the following:
- Set
include_main_docs
andinclude_version_docs
to False - Set
include_main_openapi_route
andinclude_version_openapi_route
to False if you need to customize the OpenAPI schema. - Pass a
callback
param toVersionizer
and add your own docs/OpenAPI routes manually for each version - If you want a "main" docs page, with all versioned routes included, you can manually add a docs/OpenAPI route to the versioned FastAPI app returned by
Versionizer.versionize()
.
- Set
- See the Docs Customization example for more details
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for fastapi_versionizer-2.1.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 47fb77c2fdfd3788e5846386d8b15bb0eec7185c313c1adfa65970846e4786b2 |
|
MD5 | 7eca2af0a6ab3e6bc8bdca0d8c10944e |
|
BLAKE2b-256 | d113b0562ecddb35295dcf6ee124c1105a311efa98a10752da91f88d90d401ea |