OpenAPI schema customization in FastAPI - Performance & Optimization

Performance: OpenAPI schema customization

MEDIUM IMPACT

This affects the initial page load speed of API documentation and the bundle size of the OpenAPI schema served to clients.

Serving API documentation with a large default OpenAPI schema

FastAPI

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

# Custom OpenAPI schema to reduce size

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom API",
        version="1.0.0",
        routes=app.routes,
    )
    # Remove unused schemas or paths here
    openapi_schema['paths'] = {k: v for k, v in openapi_schema['paths'].items() if k == '/items/'}
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

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

By customizing the OpenAPI schema, only necessary paths are included, reducing payload size and speeding up docs load.

📈 Performance GainReduces API docs bundle size by 70-90%, improving LCP by 150-400ms

Serving API documentation with a large default OpenAPI schema

FastAPI

from fastapi import FastAPI
app = FastAPI()

# No schema customization, default large schema generated
@app.get('/items/')
async def read_items():
    return [{'item_id': 'foo'}]

The default OpenAPI schema includes all routes and models, which can be large and slow to load in the docs UI.

📉 Performance CostAdds 50-200kb to initial API docs bundle, increasing LCP by 200-500ms on slow networks

Performance Comparison

Pattern	Payload Size	Network Impact	Parsing Cost	Verdict
Default OpenAPI schema	150-200kb	High network load	High CPU parsing	[X] Bad
Customized minimal schema	20-50kb	Low network load	Low CPU parsing	[OK] Good

Rendering Pipeline

The OpenAPI schema JSON is fetched by the browser to render the API docs UI. Larger schemas increase network transfer time and parsing cost, delaying the Largest Contentful Paint (LCP).

→Network Transfer

→Parsing

→Rendering

⚠️ BottleneckNetwork Transfer and Parsing of large JSON schema

Core Web Vital Affected

LCP

This affects the initial page load speed of API documentation and the bundle size of the OpenAPI schema served to clients.

Optimization Tips

1Customize OpenAPI schema to include only necessary endpoints.

2Avoid large unused models in the schema to reduce JSON size.

3Check schema payload size in DevTools Network tab to monitor impact.

Performance Quiz - 3 Questions

How does customizing the OpenAPI schema affect API docs performance?

A It reduces the JSON size, speeding up docs loading

B It increases the number of API routes served

C It disables API documentation completely

D It adds more CSS styles to the docs UI

DevTools: Network

How to check: Open DevTools, go to Network tab, filter by 'openapi.json' or 'docs', reload page, check size and load time of schema JSON file.

What to look for: Look for large payload size and long download time indicating heavy schema impacting LCP.