Extending OpenAPI¶
There are some cases where you might need to modify the generated OpenAPI schema.
In this section you will see how.
The normal process¶
The normal (default) process, is as follows.
AFastAPI application (instance) has an.openapi() method that is expected to return the OpenAPI schema.
As part of the application object creation, apath operation for/openapi.json (or for whatever you set youropenapi_url) is registered.
It just returns a JSON response with the result of the application's.openapi() method.
By default, what the method.openapi() does is check the property.openapi_schema to see if it has contents and return them.
If it doesn't, it generates them using the utility function atfastapi.openapi.utils.get_openapi.
And that functionget_openapi() receives as parameters:
title: The OpenAPI title, shown in the docs.version: The version of your API, e.g.2.5.0.openapi_version: The version of the OpenAPI specification used. By default, the latest:3.1.0.summary: A short summary of the API.description: The description of your API, this can include markdown and will be shown in the docs.routes: A list of routes, these are each of the registeredpath operations. They are taken fromapp.routes.
Info
The parametersummary is available in OpenAPI 3.1.0 and above, supported by FastAPI 0.99.0 and above.
Overriding the defaults¶
Using the information above, you can use the same utility function to generate the OpenAPI schema and override each part that you need.
For example, let's addReDoc's OpenAPI extension to include a custom logo.
NormalFastAPI¶
First, write all yourFastAPI application as normally:
fromfastapiimportFastAPIfromfastapi.openapi.utilsimportget_openapiapp=FastAPI()@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]defcustom_openapi():ifapp.openapi_schema:returnapp.openapi_schemaopenapi_schema=get_openapi(title="Custom title",version="2.5.0",summary="This is a very custom OpenAPI schema",description="Here's a longer description of the custom **OpenAPI** schema",routes=app.routes,)openapi_schema["info"]["x-logo"]={"url":"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"}app.openapi_schema=openapi_schemareturnapp.openapi_schemaapp.openapi=custom_openapiGenerate the OpenAPI schema¶
Then, use the same utility function to generate the OpenAPI schema, inside acustom_openapi() function:
fromfastapiimportFastAPIfromfastapi.openapi.utilsimportget_openapiapp=FastAPI()@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]defcustom_openapi():ifapp.openapi_schema:returnapp.openapi_schemaopenapi_schema=get_openapi(title="Custom title",version="2.5.0",summary="This is a very custom OpenAPI schema",description="Here's a longer description of the custom **OpenAPI** schema",routes=app.routes,)openapi_schema["info"]["x-logo"]={"url":"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"}app.openapi_schema=openapi_schemareturnapp.openapi_schemaapp.openapi=custom_openapiModify the OpenAPI schema¶
Now you can add the ReDoc extension, adding a customx-logo to theinfo "object" in the OpenAPI schema:
fromfastapiimportFastAPIfromfastapi.openapi.utilsimportget_openapiapp=FastAPI()@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]defcustom_openapi():ifapp.openapi_schema:returnapp.openapi_schemaopenapi_schema=get_openapi(title="Custom title",version="2.5.0",summary="This is a very custom OpenAPI schema",description="Here's a longer description of the custom **OpenAPI** schema",routes=app.routes,)openapi_schema["info"]["x-logo"]={"url":"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"}app.openapi_schema=openapi_schemareturnapp.openapi_schemaapp.openapi=custom_openapiCache the OpenAPI schema¶
You can use the property.openapi_schema as a "cache", to store your generated schema.
That way, your application won't have to generate the schema every time a user opens your API docs.
It will be generated only once, and then the same cached schema will be used for the next requests.
fromfastapiimportFastAPIfromfastapi.openapi.utilsimportget_openapiapp=FastAPI()@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]defcustom_openapi():ifapp.openapi_schema:returnapp.openapi_schemaopenapi_schema=get_openapi(title="Custom title",version="2.5.0",summary="This is a very custom OpenAPI schema",description="Here's a longer description of the custom **OpenAPI** schema",routes=app.routes,)openapi_schema["info"]["x-logo"]={"url":"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"}app.openapi_schema=openapi_schemareturnapp.openapi_schemaapp.openapi=custom_openapiOverride the method¶
Now you can replace the.openapi() method with your new function.
fromfastapiimportFastAPIfromfastapi.openapi.utilsimportget_openapiapp=FastAPI()@app.get("/items/")asyncdefread_items():return[{"name":"Foo"}]defcustom_openapi():ifapp.openapi_schema:returnapp.openapi_schemaopenapi_schema=get_openapi(title="Custom title",version="2.5.0",summary="This is a very custom OpenAPI schema",description="Here's a longer description of the custom **OpenAPI** schema",routes=app.routes,)openapi_schema["info"]["x-logo"]={"url":"https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"}app.openapi_schema=openapi_schemareturnapp.openapi_schemaapp.openapi=custom_openapiCheck it¶
Once you go tohttp://127.0.0.1:8000/redoc you will see that you are using your custom logo (in this example,FastAPI's logo):
