Skip to main content

OpenAPI & Metadata

FastAPI automatically generates an OpenAPI schema for your entire API, which powers the interactive documentation (Swagger UI and ReDoc). This schema is constructed by inspecting your path operations, models, and security requirements.

Application Metadata​

When you instantiate the FastAPI class in fastapi/applications.py, you can provide global metadata that appears at the top of your API documentation.

from fastapi import FastAPI

app = FastAPI(
    title="ChimichangApp",
    summary="Deadpond's favorite app. Nuff said.",
    description="""
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.
""",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
)

Internally, these parameters are passed to the get_openapi utility function in fastapi/openapi/utils.py, which constructs the info object of the OpenAPI specification.

Path Operation Metadata​

You can customize the metadata for individual endpoints using parameters in the path operation decorators (like @app.get()). These parameters are stored in the APIRoute class in fastapi/routing.py.

Tags, Summary, and Description​

Use tags to group operations in the UI, summary for a short title, and description for detailed documentation (supporting Markdown).

@app.get("/items/", tags=["items"], summary="Read Items", description="Read all items from the database")
async def read_items():
    return [{"item_id": "portal-gun"}]

If you don't provide a summary, FastAPI automatically generates one from the function name (e.g., read_items becomes "Read Items") using generate_operation_summary in fastapi/openapi/utils.py.

Response Description and Deprecation​

You can also document the success response and mark endpoints as deprecated:

@app.get("/old-items/", tags=["items"], response_description="The list of items", deprecated=True)
async def read_old_items():
    return [{"item_id": "old-portal-gun"}]

Detailed Tag Metadata​

To add descriptions or external documentation links to the tags themselves, pass a list of dictionaries to the openapi_tags parameter of the FastAPI constructor.

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)

@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}]

Custom OpenAPI Extensions​

If you need to add custom "x-attributes" to a specific path operation that are not covered by standard FastAPI parameters, use openapi_extra.

@app.get("/items/", openapi_extra={"x-custom-extension": "value"})
def route_with_extras():
    return {"message": "Hello World"}

The get_openapi_path function in fastapi/openapi/utils.py uses deep_dict_update to merge your openapi_extra dictionary into the generated operation object.

Manual Schema Customization​

FastAPI caches the generated schema in the app.openapi_schema attribute. The app.openapi() method in fastapi/applications.py checks this cache before generating a new schema.

To modify the schema manually, you can override the app.openapi method:

from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_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 schema",
        routes=app.routes,
    )
    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

Configuring Documentation URLs​

You can change the paths where the OpenAPI schema and interactive docs are served, or disable them entirely by setting them to None in the FastAPI constructor.

app = FastAPI(
    openapi_url="/api/v1/openapi.json",
    docs_url="/documentation",
    redoc_url=None
)
  • openapi_url: The location of the raw JSON schema (default: /openapi.json).
  • docs_url: The Swagger UI interactive documentation (default: /docs).
  • redoc_url: The ReDoc interactive documentation (default: /redoc).

If you set openapi_url=None, both docs_url and redoc_url are automatically disabled because they depend on the schema.