How do you document multiple response schemas in OpenAPI?

WHAT THIS TESTS: 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.

A GOOD ANSWER COVERS: 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.

COMMON WRONG ANSWERS: 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.

LIKELY FOLLOW-UPS: 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.

ONE 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.

Source: fastapi.tiangolo.com