Package: versioned-fastapi
Versioned FastAPIVersioned FastAPI simplifies the versioning ofFastAPIweb 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 likeFastAPI Versionizermight 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.CreditThis project is inspired byFastAPI Versionizerbut is mainly
designed for versioning of single endpoints.Installationpip install versioned-fastapiUsageFor more examples see theexamplesdirectory.A minimalistic example of how to use Versioned FastAPI:fromtypingimportDict,UnionfromfastapiimportFastAPI,APIRouter,HTTPExceptionfrompydanticimportBaseModelfromversioned_fastapiimportversion,FastApiVersioner# Versioned modelsclassItem(BaseModel):id:intname:strclassItemV2(BaseModel):id:intname:strdescription:str# Example dbdb:Dict[int,Union[Item,ItemV2]]={}# Create the FastAPI app ...app=FastAPI(title="Versioned FastAPI",description="Simple example of Versioned FastAPI.",)# ... and routers as normalitems_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)asyncdefcreate_item(item:Item):db[item.id]=itemreturnitem# This endpoint will be available at "/v1/items"@version(2)@items_router.post("",status_code=201)asyncdefcreate_item_v2(item:ItemV2)->ItemV2:db[item.id]=itemreturnitem# This endpoint will be available at "/v1/items/{item_id}"@version(1)@items_router.get("/{item_id}")asyncdefget_item(item_id:int)->Union[Item,ItemV2]:ifitem_idindb:returndb[item_id]raiseHTTPException(status_code=404,detail="Item not found")app.include_router(items_router)# Version your app# It will add version prefixes and customize the swagger docsversions=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/itemsPOST /v2/itemsGET /v1/items/{items_id}GET /openapi.jsonThe openapi definition containing all routes of all versionsGET /v1/openapi.jsonThe openapi definition containing all routes of version 1GET /v2/openapi.jsonThe openapi definition containing all routes of version 2GET /docsThe customized Swagger documentationCustomizationTo 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 (seecustomization example) 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 mindCurrently, the versioning of websockets is not supported, but this might be added in the futureThe Redoc documentation will not be modified and will always show all routes of all versionsIf you customized your swagger docs, this might conflict with the docs route created by this packageIf you customized the openapi endpoint, this will not affect the versioned endpoints