Additional Responses in OpenAPI¶

You can declare additional responses, with additional status codes, media types, descriptions, etc.

Those additional responses will be included in the OpenAPI schema, so they will also appear in the API docs.

But for those additional responses you have to make sure you return aResponse likeJSONResponse directly, with your status code and content.

Additional Response withmodel¶

You can pass to yourpath operation decorators a parameterresponses.

It receives adict: the keys are status codes for each response (like200), and the values are otherdicts with the information for each of them.

Each of those responsedicts can have a keymodel, containing a Pydantic model, just likeresponse_model.

FastAPI will take that model, generate its JSON Schema and include it in the correct place in OpenAPI.

For example, to declare another response with a status code404 and a Pydantic modelMessage, you can write:

fromfastapiimportFastAPIfromfastapi.responsesimportJSONResponsefrompydanticimportBaseModelclassItem(BaseModel):id:strvalue:strclassMessage(BaseModel):message:strapp=FastAPI()@app.get("/items/{item_id}",response_model=Item,responses={404:{"model":Message}})asyncdefread_item(item_id:str):ifitem_id=="foo":return{"id":"foo","value":"there goes my hero"}returnJSONResponse(status_code=404,content={"message":"Item not found"})

The generated responses in the OpenAPI for thispath operation will be:

{"responses":{"404":{"description":"Additional Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}

The schemas are referenced to another place inside the OpenAPI schema:

{"components":{"schemas":{"Message":{"title":"Message","required":["message"],"type":"object","properties":{"message":{"title":"Message","type":"string"}}},"Item":{"title":"Item","required":["id","value"],"type":"object","properties":{"id":{"title":"Id","type":"string"},"value":{"title":"Value","type":"string"}}},"ValidationError":{"title":"ValidationError","required":["loc","msg","type"],"type":"object","properties":{"loc":{"title":"Location","type":"array","items":{"type":"string"}},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}}},"HTTPValidationError":{"title":"HTTPValidationError","type":"object","properties":{"detail":{"title":"Detail","type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}}}}}

Additional media types for the main response¶

You can use this sameresponses parameter to add different media types for the same main response.

For example, you can add an additional media type ofimage/png, declaring that yourpath operation can return a JSON object (with media typeapplication/json) or a PNG image:

fromfastapiimportFastAPIfromfastapi.responsesimportFileResponsefrompydanticimportBaseModelclassItem(BaseModel):id:strvalue:strapp=FastAPI()@app.get("/items/{item_id}",response_model=Item,responses={200:{"content":{"image/png":{}},"description":"Return the JSON item or an image.",}},)asyncdefread_item(item_id:str,img:bool|None=None):ifimg:returnFileResponse("image.png",media_type="image/png")else:return{"id":"foo","value":"there goes my hero"}

Combining information¶

You can also combine response information from multiple places, including theresponse_model,status_code, andresponses parameters.

You can declare aresponse_model, using the default status code200 (or a custom one if you need), and then declare additional information for that same response inresponses, directly in the OpenAPI schema.

FastAPI will keep the additional information fromresponses, and combine it with the JSON Schema from your model.

For example, you can declare a response with a status code404 that uses a Pydantic model and has a customdescription.

And a response with a status code200 that uses yourresponse_model, but includes a customexample:

fromfastapiimportFastAPIfromfastapi.responsesimportJSONResponsefrompydanticimportBaseModelclassItem(BaseModel):id:strvalue:strclassMessage(BaseModel):message:strapp=FastAPI()@app.get("/items/{item_id}",response_model=Item,responses={404:{"model":Message,"description":"The item was not found"},200:{"description":"Item requested by ID","content":{"application/json":{"example":{"id":"bar","value":"The bar tenders"}}},},},)asyncdefread_item(item_id:str):ifitem_id=="foo":return{"id":"foo","value":"there goes my hero"}else:returnJSONResponse(status_code=404,content={"message":"Item not found"})

It will all be combined and included in your OpenAPI, and shown in the API docs:

Combine predefined responses and custom ones¶

You might want to have some predefined responses that apply to manypath operations, but you want to combine them with custom responses needed by eachpath operation.

For those cases, you can use the Python technique of "unpacking" adict with**dict_to_unpack:

old_dict={"old key":"old value","second old key":"second old value",}new_dict={**old_dict,"new key":"new value"}

Here,new_dict will contain all the key-value pairs fromold_dict plus the new key-value pair:

{"old key":"old value","second old key":"second old value","new key":"new value",}

You can use that technique to reuse some predefined responses in yourpath operations and combine them with additional custom ones.

For example:

fromfastapiimportFastAPIfromfastapi.responsesimportFileResponsefrompydanticimportBaseModelclassItem(BaseModel):id:strvalue:strresponses={404:{"description":"Item not found"},302:{"description":"The item was moved"},403:{"description":"Not enough privileges"},}app=FastAPI()@app.get("/items/{item_id}",response_model=Item,responses={**responses,200:{"content":{"image/png":{}}}},)asyncdefread_item(item_id:str,img:bool|None=None):ifimg:returnFileResponse("image.png",media_type="image/png")else:return{"id":"foo","value":"there goes my hero"}

More information about OpenAPI responses¶

To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification:

• OpenAPI Responses Object, it includes theResponse Object.
• OpenAPI Response Object, you can include anything from this directly in each response inside yourresponses parameter. Includingdescription,headers,content (inside of this is that you declare different media types and JSON Schemas), andlinks.