OpenAPI schema customization in FastAPI - Step-by-Step Execution

Concept Flow - OpenAPI schema customization

Start FastAPI app

↓

Define API endpoints

↓

Customize OpenAPI schema function

↓

Assign custom schema to app.openapi

↓

Run app and access /openapi.json

↓

See customized schema output

This flow shows how FastAPI lets you replace the default OpenAPI schema with your own custom version.

Execution Sample

FastAPI

from fastapi import FastAPI
app = FastAPI()

@app.get("/items")
async def read_items():
    return [{"item_id": "foo"}]

# Custom OpenAPI schema
original_openapi = app.openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = original_openapi()
    openapi_schema["info"]["title"] = "Custom API"
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

This code creates a FastAPI app with one endpoint and replaces the OpenAPI schema to change the API title.

Execution Table

Step	Action	Function Called	Schema State	Output
1	Start app	FastAPI()	None	App instance created
2	Define /items endpoint	@app.get	None	Endpoint registered
3	Save original openapi	app.openapi	None	Original schema function saved
4	Define custom_openapi	custom_openapi()	None	Function ready to override
5	Assign custom_openapi	app.openapi = custom_openapi	None	Override set
6	Call app.openapi()	custom_openapi()	None	Calls original_openapi()
7	Generate default schema	original_openapi()	None	Default schema dict created
8	Modify schema title	custom_openapi()	Default schema	Title changed to 'Custom API'
9	Cache schema	custom_openapi()	Modified schema	Schema cached in app.openapi_schema
10	Return schema	custom_openapi()	Modified schema	Custom schema returned
11	Subsequent calls	custom_openapi()	Cached schema	Cached schema returned
12	Access /openapi.json	FastAPI internal	Cached schema	Custom schema JSON served

💡 Custom schema cached and served instead of default after first call

Variable Tracker

Variable	Start	After Step 6	After Step 8	After Step 9	Final
app.openapi_schema	None	None	None	Modified schema dict	Modified schema dict
original_openapi	Function	Function	Function	Function	Function
openapi_schema	None	Default schema dict	Modified schema dict	Modified schema dict	Modified schema dict

Key Moments - 3 Insights

Why does the custom_openapi function check if app.openapi_schema exists before generating the schema?

To avoid regenerating the schema multiple times, it returns the cached schema if available, as shown in step 6 and 11 of the execution_table.

How does assigning app.openapi = custom_openapi change the behavior of the FastAPI app?

It replaces the default schema generator with the custom function, so when the schema is requested (step 6), the custom logic runs instead of the default.

What happens if you don't cache the modified schema in app.openapi_schema?

The schema would be regenerated on every request, causing unnecessary computation and possibly inconsistent results, unlike the caching shown in step 9.

Visual Quiz - 3 Questions

Look at the execution_table at step 8, what change is made to the schema?

A The API title is changed to 'Custom API'

B The endpoint path is removed

C The schema is deleted

D The schema version is changed

💡 Hint

Check the 'Schema State' and 'Output' columns at step 8 in the execution_table

At which step does the custom schema get cached to avoid regeneration?

A Step 6

B Step 9

C Step 3

D Step 11

💡 Hint

Look for when app.openapi_schema is assigned in the execution_table

If you remove the line 'app.openapi = custom_openapi', what happens when accessing /openapi.json?

A An error occurs

B No schema is served

C The default schema is served

D The custom schema is still served

💡 Hint

Refer to step 5 where the override is assigned and what happens if it is missing

Concept Snapshot

FastAPI lets you replace the default OpenAPI schema by assigning a custom function to app.openapi.
This function can call the original schema generator, modify the schema dict, and cache it.
The custom schema is then served at /openapi.json instead of the default.
Caching the schema avoids repeated computation.
This is useful to change titles, descriptions, or add metadata.

Full Transcript

This visual execution trace shows how to customize the OpenAPI schema in FastAPI. First, you create a FastAPI app and define endpoints. Then you save the original openapi function. Next, you define a custom function that calls the original, modifies the schema (like changing the title), caches it, and returns it. You assign this custom function to app.openapi. When the app runs and the schema is requested, the custom function runs, returning the modified schema. The schema is cached to avoid regenerating it on every request. This process lets you change how the API schema looks without changing endpoint code.