Package: fastapi-versionizer
FastAPI VersionizerCreditThis was inspired byfastapi_versioning.
This project addresses issues withfastapi_versioningand adds some additional features.Installationpip install fastapi-versionizerExamplesYou can find examples in theexamplesdirectory.SummaryFastAPI Versionizermakes API versioning easy.Here is a simple (and rather contrived) example:fromtypingimportListfromfastapiimportFastAPI,APIRouterfrompydanticimportBaseModelfromfastapi_versionizer.versionizerimportVersionizer,api_versionclassUser(BaseModel):id:intname:strclassUserV2(BaseModel):id:intname:strage:intdb={'users':{}}app=FastAPI(title='test',redoc_url=None)users_router=APIRouter(prefix='/users',tags=['Users'])@app.get('/status',tags=['Status'])defget_status()->str:return'Ok'@api_version(1)@users_router.get('',deprecated=True)defget_users()->List[User]:returnlist(userforuserindb['users'].values()ifisinstance(user,User))@api_version(1)@users_router.post('',deprecated=True)defcreate_user(user:User)->User:db['users'][user.id]=userreturnuser@api_version(2)@users_router.get('')defget_users_v2()->List[UserV2]:returnlist(userforuserindb['users'].values()ifisinstance(user,UserV2))@api_version(2)@users_router.post('')defcreate_user_v2(user:UserV2)->UserV2:db['users'][user.id]=userreturnuserapp.include_router(users_router)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.jsonOpenAPI schema with endpoints from all versionsGET /docsSwagger page with endpoints from all versionsGET /v1/openapi.jsonOpenAPI schema for v1 endpointsGET /v1/docsSwagger page for v1 endpointsGET /v1/statusGET /v1/usersPOST /v1/usersGET /v2/openapi.jsonOpenAPI schema for v2 endpointsGET /v2/docsSwagger page for v2 endpointsGET /v2/statusThis gets carried on from v1, where it was introduced, but has the same implementationGET /v2/usersPOST /v2/usersGET /latest/openapi.jsonOpenAPI schema for latest (i.e. v2) endpointsGET /latest/docsSwagger page for latest (i.e. v2) endpointsGET /latest/statusGET /latest/usersPOST /latest/usersDetailsFastAPI Versionizerworks by modifying a FastAPI app in place, adding versioned routes and proper docs pages.
Routes are annotated with version information, using the@api_versiondecorator.
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 theprefix_formatparameter described below,Versionizer ParametersappThe FastAPI you want to versionprefix_formatUsed 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_formatUsed to build the semantic version, which is shown in docs.Examples: "{major}", "{major}.{minor}"default_versionDefault version used if a route is not annotated with @api_version.latest_prefixIf 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_docsIf True, docs page(s) will be created at the root, with all versioned routes includedinclude_main_openapi_routeIf True, an OpenAPI route will be created at the root, with all versioned routes includedinclude_version_docsIf True, docs page(s) will be created for each versioninclude_version_openapi_routeIf True, an OpenAPI route will be created for each versioninclude_versions_routeIf True, a "GET /versions" route will be added, which includes information about all API versionssort_routesIf 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.callbackA 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 routerVersion (in tuple form)Version path prefixDocs CustomizationThere 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'sdocs_urlandredoc_url.If these are set to None, docs pages will not be generated.Swagger UI parameters can be controlled by setting your FastAPI app'sswagger_ui_parametersIf you want to customize your docs beyond whatFastAPI Versionizercan handle, you can do the following:Setinclude_main_docsandinclude_version_docsto FalseSetinclude_main_openapi_routeandinclude_version_openapi_routeto False if you need to customize the OpenAPI schema.Pass acallbackparam toVersionizerand add your own docs/OpenAPI routes manually for each versionIf 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 byVersionizer.versionize().See theDocs Customizationexample for more details