Overriding FastAPI's OpenAPI Generator

WHY IT EXISTS: FastAPI automatically builds an OpenAPI schema from your routes, models, and dependencies. That works until business requirements outgrow the defaults. You might need to inject fields the framework does not support, strip out internal-only paths, or merge schemas owned by another team. Rather than maintaining a separate static spec, overriding the generator lets you keep the automatic parts while surgically altering the output.

THE MENTAL MODEL: Think of app.openapi as a hook rather than a static property. FastAPI calls this function whenever something needs the schema, such as the docs UI or an export endpoint. By assigning your own function to app.openapi, you intercept that call, run the original logic or skip it, and return a modified dict. It is middleware for metadata.

HOW IT WORKS: You define a function that optionally calls the original generator, modifies the resulting dictionary, and assigns it back to app.openapi. A common pattern is to call the superclass method via app.openapi_schema or by stashing the original function in a closure. Because the result is a plain Python dict, you can pop paths, add x- extensions, rewrite security schemes, or inject examples. The function should cache the result on the app instance so subsequent calls return the same object without rebuilding.

WHEN TO USE IT: Reach for this when you need vendor extensions like x-codeSamples or x-tagGroups, when you want a public schema that omits admin endpoints, or when you are federating multiple services and need to stitch their schemas into one document. It is also useful for adding examples or descriptions that are too verbose to embed in Pydantic model configs.

WHEN NOT TO USE IT: Do not override the generator to fix type annotations or validation logic. If your schema is wrong because of incorrect models, fix the models. Avoid this for simple sorting or tagging changes that FastAPI already supports through parameters. Also skip it if you only need to serve a completely static file; in that case, mount a static route and bypass generation entirely.

ONE CANONICAL EXAMPLE: A platform exposes a public developer portal but keeps health checks and admin routes in the same app. The team overrides app.openapi to call the original generator, then iterates over paths to remove any route tagged with admin. They also inject an x-logo vendor extension into the info block. The override caches the cleaned dict on app.openapi_schema, so the swagger-ui and redoc endpoints serve the filtered schema instantly on every request without recomputing.