How do you document multiple response schemas in OpenAPI?
This tests FastAPI OpenAPI schema generation for error responses. A strong answer covers the decorator responses dict mapping status codes to Pydantic models and descriptions, plus manually returning JSONResponse with that code.
What's really being asked
This question probes your understanding of FastAPI's OpenAPI generation capabilities beyond the default success response. The interviewer wants to know if you can statically declare error contracts so that generated docs and client SDKs remain accurate, and whether you understand the separation between schema declaration and runtime response construction.
The full answer
First, mention the responses parameter available on path operation decorators such as app.get or app.post. This parameter takes a dictionary where keys are integer status codes and values are dictionaries that can include a Pydantic model, a description string, and content type details. Second, explain that declaring a response in this dictionary adds it to the OpenAPI schema and the automatic documentation UI, but it does not change the function's return type validation or automatic serialization. Third, emphasize that for any additional status code beyond the default, you must manually instantiate and return a Response subclass such as JSONResponse with the desired status code and body, because FastAPI will not automatically switch status codes based on the responses dictionary alone. Fourth, note that you can combine the predefined response_model for the main success case with the responses dictionary for extra codes, and you can also override media types per status code if needed.
The mistakes people make
A major red flag is claiming that setting response_model to a Union of models will document multiple status codes; response_model only defines the default success response schema. Another mistake is asserting that raising HTTPException is sufficient to document the error schema in OpenAPI, since HTTPException does not accept a Pydantic model for its body in the schema. Some candidates also forget that the responses dictionary is purely declarative and neglect to mention the need to return the matching Response object at runtime.
What usually comes next
The interviewer may ask how to document a response that has no body, such as a 204 No Content, which you can do by setting model to None in the responses dictionary. They might also ask how to reuse a common error model across many endpoints, which you can achieve by defining a single Pydantic model and referencing it in multiple responses dictionaries. A deeper follow-up is how to handle multiple media types for the same status code, which FastAPI supports by nesting content types under the status code key.
A concrete example
Suppose you have an endpoint that reads a user by ID. You could set the decorator parameter responses to a dictionary where the key 404 maps to a dictionary with model set to ErrorMessage and description set to User not found, and the key 500 maps to a similar structure. The function itself would still declare response_model set to UserOut for the 200 case. In the function body, if the user is missing, you would return a JSONResponse with status_code set to 404 and content set to an ErrorMessage instance converted to a dictionary. This ensures the 404 schema appears in Swagger UI while your runtime behavior matches the contract.
Interview question
To document a 200 UserOut response and a 404 ErrorMessage in FastAPI's OpenAPI schema, which approach correctly handles both schema generation and runtime behavior?
- a.Set response_model to Union[UserOut, ErrorMessage] so FastAPI infers status codes from the union
- b.Raise HTTPException with detail set to an ErrorMessage instance whenever the user is missing
- c.Set response_model to UserOut and return an ErrorMessage dict for 404, expecting FastAPI to automatically assign the 404 status code
- d.Define a responses dict with 404 mapped to ErrorMessage and manually return JSONResponse with status_code 404 when neededCorrect
Why? this is the answer
The responses dictionary statically declares the 404 schema in OpenAPI, but because it is purely declarative you must still manually return a JSONResponse with that status code at runtime. Setting response_model to a Union only defines the default success schema and cannot generate separate per-status-code documentation.
Just read this? Test yourself on what you have been reading.
Read the original → fastapi.tiangolo.com
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on fastapi — each one lists the topics its interview covers.
See open roles