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.

Practice

1. What is the main purpose of customizing the OpenAPI schema in a FastAPI application?

easy

A. To provide clear API documentation with custom titles, descriptions, and versions

B. To speed up the API response time

C. To change the database connection settings

D. To automatically generate frontend UI components

Solution

1. Step 1: Understand OpenAPI schema role

   The OpenAPI schema defines how the API is documented and described for users and tools.

2. Step 2: Identify customization benefits

   Customizing it lets you add titles, descriptions, versions, and contact info to make docs clearer.

3. Final Answer:

   To provide clear API documentation with custom titles, descriptions, and versions -> Option A

4. Quick Check:

   OpenAPI schema customization = clear docs [OK]

Hint: Think: OpenAPI schema = API documentation details [OK]

Common Mistakes:

• Confusing schema customization with performance tuning
• Thinking it changes database or backend logic
• Assuming it auto-generates frontend code

2. Which of the following is the correct way to set a custom title and version for your FastAPI app's OpenAPI schema?

easy

A. app = FastAPI(schema_title="My API", schema_version="1.0.0")

B. app = FastAPI(openapi_title="My API", openapi_version="1.0.0")

C. app = FastAPI(title="My API", version="1.0.0")

D. app = FastAPI(api_title="My API", api_version="1.0.0")

Solution

1. Step 1: Recall FastAPI app parameters

   FastAPI accepts title and version as direct parameters in its constructor.

2. Step 2: Match correct parameter names

   The correct parameters are exactly title and version, not schema_title or openapi_title.

3. Final Answer:

   app = FastAPI(title="My API", version="1.0.0") -> Option C

4. Quick Check:

   FastAPI(title, version) = correct syntax [OK]

Hint: Use 'title' and 'version' directly in FastAPI() [OK]

Common Mistakes:

• Using incorrect parameter names like openapi_title
• Trying to set schema properties after app creation
• Confusing app config with route decorators

3. Given this FastAPI app code, what will be the OpenAPI docs URL by default?

from fastapi import FastAPI
app = FastAPI(title="Test API")

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

medium

A. /api-docs

B. /openapi.json

C. /swagger

D. /docs

Solution

1. Step 1: Recall FastAPI default docs path

   FastAPI by default serves Swagger UI at the path /docs.

2. Step 2: Differentiate docs and schema URLs

   /openapi.json is the raw schema JSON, not the interactive docs UI.

3. Final Answer:

   /docs -> Option D

4. Quick Check:

   Default docs URL = /docs [OK]

Hint: Swagger UI docs default path is /docs in FastAPI [OK]

Common Mistakes:

• Confusing /openapi.json with docs UI
• Assuming /swagger or /api-docs are default
• Not knowing FastAPI defaults for docs

4. What is wrong with this FastAPI app code if the goal is to hide the automatic docs UI?

app = FastAPI(docs_url=None)

@app.get("/users")
async def get_users():
    return [{"name": "Alice"}]

medium

A. docs_url should be set to False, not None

B. You must also set redoc_url=None to hide all docs

C. docs_url parameter does not exist in FastAPI

D. docs_url=None is correct and will hide docs UI

Solution

1. Step 1: Understand docs_url and redoc_url

   FastAPI has two docs UIs: Swagger UI at docs_url and ReDoc at redoc_url.

2. Step 2: Check hiding docs UI fully

   Setting docs_url=None hides Swagger UI but ReDoc remains unless redoc_url=None is also set.

3. Final Answer:

   You must also set redoc_url=None to hide all docs -> Option B

4. Quick Check:

   Hide all docs = docs_url=None + redoc_url=None [OK]

Hint: Set both docs_url and redoc_url to None to hide docs [OK]

Common Mistakes:

• Assuming docs_url=None hides all docs
• Using invalid values like False for docs_url
• Not knowing about ReDoc docs URL

5. You want to customize your FastAPI app's OpenAPI schema to include a contact email and license info. Which code snippet correctly achieves this?

hard

A. app = FastAPI(contact={"email": "[e-mail]"}, license_info={"name": "MIT"})

B. app = FastAPI(openapi_info={"contact": {"email": "[e-mail]"}, "license": {"name": "MIT"}})

C. app = FastAPI(openapi_contact={"email": "[e-mail]"}, openapi_license={"name": "MIT"})

D. app = FastAPI(openapi_contact_email="[e-mail]", openapi_license_name="MIT")

Solution

1. Step 1: Recall FastAPI parameters for contact and license

   FastAPI uses contact and license_info parameters to customize OpenAPI schema contact and license sections.

2. Step 2: Match correct parameter names and structure

   contact and license_info expect dictionaries with keys like email and name respectively.

3. Final Answer:

   app = FastAPI(contact={"email": "[e-mail]"}, license_info={"name": "MIT"}) -> Option A

4. Quick Check:

   Use contact and license_info dicts in FastAPI() [OK]

Hint: Use contact and license_info dicts in FastAPI() constructor [OK]

Common Mistakes:

• Using openapi_contact or openapi_license which are invalid
• Trying to nest contact inside openapi_info
• Passing strings instead of dicts for contact/license