Skip to content
C Codeloom
FastAPI

FastAPI OpenAPI Customization: A Practical Tutorial

Tailor FastAPI's auto-generated OpenAPI schema: tags, summaries, examples, response models, custom operation IDs, security schemes, and a custom Swagger UI your team will actually use.

·4 min read · By Codeloom
Intermediate 11 min read

What you'll learn

  • ✓How FastAPI builds the OpenAPI schema
  • ✓Adding tags, summaries, and rich descriptions
  • ✓Multiple response models and status codes
  • ✓Examples that improve client SDK output
  • ✓Custom operation IDs and security schemes
  • ✓Overriding the OpenAPI schema entirely when needed

Prerequisites

  • •Familiarity with FastAPI routes and Pydantic models

FastAPI gives you a free OpenAPI schema and Swagger UI. That alone is great. With a small amount of polish, the same schema becomes a real product surface: better docs, cleaner generated SDKs, and fewer support questions.

What and Why

OpenAPI is a JSON description of your API: every path, parameter, request body, and response, plus reusable component schemas. FastAPI builds it from your route signatures and Pydantic models. The defaults are good; the defaults are also generic. Customization is how you make the schema reflect your team’s vocabulary and your clients’ needs.

Mental Model

There are three layers of customization. At the route level, decorators accept tags, summary, description, response_model, responses, and operation_id. At the model level, Pydantic’s model_config and Field let you add titles, descriptions, and examples. At the app level, you can mutate the generated dict via a custom app.openapi() function for anything the decorators do not expose.

Hands-on Example

A polished route looks like this:

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field

app = FastAPI(
    title="Orders API",
    version="1.4.0",
    description="Internal orders service. Use the staging key in non-prod.",
)

class Order(BaseModel):
    id: int = Field(..., examples=[42])
    total_cents: int = Field(..., ge=0, examples=[1999])
    status: str = Field(..., examples=["paid"])

class ErrorResponse(BaseModel):
    detail: str

@app.get(
    "/orders/{order_id}",
    response_model=Order,
    tags=["orders"],
    summary="Fetch one order",
    description="Returns a single order by its numeric id.",
    operation_id="getOrderById",
    responses={
        404: {"model": ErrorResponse, "description": "Order not found"},
    },
)
async def get_order(order_id: int):
    if order_id != 42:
        raise HTTPException(status.HTTP_404_NOT_FOUND, "not found")
    return Order(id=42, total_cents=1999, status="paid")
Routes, models, and app-level metadata feed FastAPI's schema builder. The result powers Swagger UI, ReDoc, and code generators.

For deeper changes, override the schema:

from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title=app.title, version=app.version, routes=app.routes
    )
    schema["components"]["securitySchemes"] = {
        "ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-API-Key"}
    }
    schema["security"] = [{"ApiKeyAuth": []}]
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi

Common Pitfalls

The first pitfall is duplicate operation_ids when you have similarly named routes across routers. Generated SDKs will collide. Set operation_id explicitly for any public endpoint.

The second is documenting only success responses. Add error models to the responses mapping so generated clients can type-narrow on failures.

The third is putting examples only on routes. Examples on Field propagate to every endpoint using that model and to component schemas, where SDK generators read them.

The fourth is forgetting that response_model filters output. If you return extra fields, they will be stripped silently. That is usually what you want, but it surprises new contributors.

The fifth is overriding app.openapi without caching. Rebuilding the schema on every request is slow and breaks the docs UI under load.

Practical Tips

Group routes with tags and add openapi_tags metadata on the app for tag descriptions. Use APIRouter prefix and tags to keep boilerplate out of every route. Treat your OpenAPI schema as part of your public contract: review changes in PR and version it.

If you ship SDKs, run a generator (openapi-generator, openapi-typescript) in CI and fail the build on breaking changes.

Wrap-up

A little OpenAPI polish turns FastAPI’s free docs into a credible product. Add tags, write summaries, declare error responses, and supply examples. When the decorators run out, override app.openapi for the final mile. Your future SDK users and your support inbox will thank you.

Related articles