How to Customize OpenAPI Schema in FastAPI

In FastAPI, you can customize the OpenAPI schema by setting parameters like title, description, and version in the FastAPI constructor. For deeper customization, override the openapi() method to modify the generated schema before it is served.

Syntax

FastAPI allows customization of the OpenAPI schema mainly in two ways:

• Basic metadata: Set title, description, version, and other info when creating the FastAPI app.
• Advanced customization: Override the openapi() method to modify the schema dictionary before it is returned.

This lets you add extra info, change existing fields, or add custom extensions.

python

from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="This API does awesome things.",
    version="1.0.0"
)

# Advanced customization example
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = app.openapi()
    openapi_schema["info"]["x-logo"] = {
        "url": "https://example.com/logo.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

Example

This example shows how to customize the OpenAPI schema by setting metadata and adding a custom logo using the openapi() override.

python

from fastapi import FastAPI

app = FastAPI(
    title="Custom API",
    description="API with customized OpenAPI schema.",
    version="2.0.0"
)

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

# Override openapi method to add custom logo

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = app.openapi()
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

Output

When you run this FastAPI app and visit /docs, the OpenAPI UI shows the custom title, description, version, and a logo in the top left corner.

Common Pitfalls

• Not caching the schema: Always cache the customized schema in app.openapi_schema to avoid regenerating it on every request.
• Incorrect schema structure: Modifying the schema dictionary incorrectly can break the OpenAPI UI. Always follow OpenAPI spec structure.
• Overriding openapi() without calling original: Always call app.openapi() inside your override to get the base schema before modifying.

python

from fastapi import FastAPI

app = FastAPI()

# Wrong: Not caching schema and missing base call
# def bad_openapi():
#     openapi_schema = {}
#     openapi_schema["info"] = {"title": "Bad API"}
#     return openapi_schema

# Correct way:
def good_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = app.openapi()
    openapi_schema["info"]["title"] = "Good API"
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = good_openapi

Quick Reference

• Basic metadata: Use FastAPI(title=..., description=..., version=...)
• Advanced: Override app.openapi() to customize schema dict
• Cache schema: Store customized schema in app.openapi_schema
• Modify schema keys: Follow OpenAPI spec keys like info, paths, components

Key Takeaways

Set basic OpenAPI metadata in the FastAPI constructor for quick customization.

Override the openapi() method to deeply customize the schema before serving it.

Always cache the customized schema in app.openapi_schema to improve performance.

Modify the schema dictionary carefully following OpenAPI specification structure.

Test your schema changes by visiting /docs or /openapi.json endpoints.