Responses Adicionales en OpenAPI¶

Puedes declarar responses adicionales, con códigos de estado adicionales, media types, descripciones, etc.

Esos responses adicionales se incluirán en el esquema de OpenAPI, por lo que también aparecerán en la documentación de la API.

Pero para esos responses adicionales tienes que asegurarte de devolver unResponse comoJSONResponse directamente, con tu código de estado y contenido.

Response Adicional conmodel¶

Puedes pasar a tusdecoradores de path operation un parámetroresponses.

Recibe undict: las claves son los códigos de estado para cada response (como200), y los valores son otrosdicts con la información para cada uno de ellos.

Cada uno de esosdicts de response puede tener una clavemodel, conteniendo un modelo de Pydantic, así comoresponse_model.

FastAPI tomará ese modelo, generará su JSON Schema y lo incluirá en el lugar correcto en OpenAPI.

Por ejemplo, para declarar otro response con un código de estado404 y un modelo PydanticMessage, puedes escribir:

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"})

Los responses generadas en el OpenAPI para estapath operation serán:

{"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"}}}}}}

Los esquemas se referencian a otro lugar dentro del esquema de OpenAPI:

{"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"}}}}}}}

Media types adicionales para el response principal¶

Puedes usar este mismo parámetroresponses para agregar diferentes media type para el mismo response principal.

Por ejemplo, puedes agregar un media type adicional deimage/png, declarando que tupath operation puede devolver un objeto JSON (con media typeapplication/json) o una imagen PNG:

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"}

Combinando información¶

También puedes combinar información de response de múltiples lugares, incluyendo los parámetrosresponse_model,status_code, yresponses.

Puedes declarar unresponse_model, usando el código de estado por defecto200 (o uno personalizado si lo necesitas), y luego declarar información adicional para ese mismo response enresponses, directamente en el esquema de OpenAPI.

FastAPI mantendrá la información adicional deresponses y la combinará con el JSON Schema de tu modelo.

Por ejemplo, puedes declarar un response con un código de estado404 que usa un modelo Pydantic y tiene unadescription personalizada.

Y un response con un código de estado200 que usa turesponse_model, pero incluye unexample personalizado:

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"})

Todo se combinará e incluirá en tu OpenAPI, y se mostrará en la documentación de la API:

Combina responses predefinidos y personalizados¶

Es posible que desees tener algunos responses predefinidos que se apliquen a muchaspath operations, pero que quieras combinarlos con responses personalizados necesarios por cadapath operation.

Para esos casos, puedes usar la técnica de Python de "desempaquetar" undict con**dict_to_unpack:

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

Aquí,new_dict contendrá todos los pares clave-valor deold_dict más el nuevo par clave-valor:

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

Puedes usar esa técnica para reutilizar algunos responses predefinidos en tuspath operations y combinarlos con otros personalizados adicionales.

Por ejemplo:

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"}

Más información sobre responses OpenAPI¶

Para ver exactamente qué puedes incluir en los responses, puedes revisar estas secciones en la especificación OpenAPI:

• Objeto de Responses de OpenAPI, incluye elResponse Object.
• Objeto de Response de OpenAPI, puedes incluir cualquier cosa de esto directamente en cada response dentro de tu parámetroresponses. Incluyendodescription,headers,content (dentro de este es que declaras diferentes media types y JSON Schemas), ylinks.