How do you directly modify FastAPI's generated OpenAPI dictionary?

What's really being asked

FastAPI generates the OpenAPI schema as a plain Python dictionary during startup or on the first request to the docs endpoint. This question tests whether you know the framework provides a hook to intercept and mutate that dictionary before it is cached and served. Senior candidates should demonstrate they understand the difference between declarative decorator tweaks and imperative programmatic control, and they should know the exact function override pattern rather than resorting to hacks.

The full answer

First, store a reference to the original app.openapi function before overriding it. Second, define a new function that calls the original to obtain the base dictionary, which preserves all normal path operation and model generation. Third, mutate that dictionary directly, for example by injecting top-level security schemes, adding custom tags, pruning internal paths, or merging in external schema fragments. Fourth, assign the mutated dictionary to app.openapi_schema so FastAPI caches it and does not regenerate it on every request. Fifth, return the mutated dictionary from the new function. Finally, assign the new function back to app.openapi. The candidate should mention that this runs lazily on first schema access unless explicitly triggered earlier.

The mistakes people make

A major red flag is suggesting middleware that intercepts requests to /openapi.json and rewrites the response body. That adds unnecessary overhead and complexity. Another red flag is modifying app.openapi_schema after the fact without wrapping the generator, which can lead to race conditions or the changes being overwritten. Candidates who suggest monkey-patching FastAPI's internal get_openapi utility or editing the JSON string directly show a lack of familiarity with the intended extension point. Simply stating you would use the openapi_url parameter or more decorators misses the point of programmatic customization.

What usually comes next

The interviewer may ask how you would serve two different OpenAPI schemas from the same app, such as a public schema and an internal schema. They might also ask when the override function actually executes, which is typically on the first request that needs the schema unless you call app.openapi() during startup. Another follow-up is how to test this override reliably in unit tests without spinning up the full application.

A concrete example

Suppose your app includes health check and admin endpoints that should not appear in the public documentation. Inside the custom app.openapi function, after calling the original generator, you iterate over openapi_schema['paths'] and remove any path whose operation metadata contains a tag of internal or admin. You then inject a global API security requirement into openapi_schema['security'] and set the version field dynamically from an environment variable before caching and returning the dict.