Cuerpo - Múltiples Parámetros¶

Ahora que hemos visto cómo usarPath yQuery, veamos usos más avanzados de las declaraciones del request body.

MezclarPath,Query y parámetros del cuerpo¶

Primero, por supuesto, puedes mezclar las declaraciones de parámetros dePath,Query y del request body libremente yFastAPI sabrá qué hacer.

Y también puedes declarar parámetros del cuerpo como opcionales, estableciendo el valor por defecto aNone:

fromtypingimportAnnotatedfromfastapiimportFastAPI,PathfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:Annotated[int,Path(title="The ID of the item to get",ge=0,le=1000)],q:str|None=None,item:Item|None=None,):results={"item_id":item_id}ifq:results.update({"q":q})ifitem:results.update({"item":item})returnresults

fromfastapiimportFastAPI,PathfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.put("/items/{item_id}")asyncdefupdate_item(*,item_id:int=Path(title="The ID of the item to get",ge=0,le=1000),q:str|None=None,item:Item|None=None,):results={"item_id":item_id}ifq:results.update({"q":q})ifitem:results.update({"item":item})returnresults

Múltiples parámetros del cuerpo¶

En el ejemplo anterior, laspath operations esperarían un cuerpo JSON con los atributos de unItem, como:

{"name":"Foo","description":"The pretender","price":42.0,"tax":3.2}

Pero también puedes declarar múltiples parámetros del cuerpo, por ejemploitem yuser:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=NoneclassUser(BaseModel):username:strfull_name:str|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item,user:User):results={"item_id":item_id,"item":item,"user":user}returnresults

En este caso,FastAPI notará que hay más de un parámetro del cuerpo en la función (hay dos parámetros que son modelos de Pydantic).

Entonces, usará los nombres de los parámetros como claves (nombres de campo) en el cuerpo, y esperará un cuerpo como:

{"item":{"name":"Foo","description":"The pretender","price":42.0,"tax":3.2},"user":{"username":"dave","full_name":"Dave Grohl"}}

FastAPI hará la conversión automática del request, de modo que el parámetroitem reciba su contenido específico y lo mismo parauser.

Realizará la validación de los datos compuestos, y los documentará así para el esquema de OpenAPI y la documentación automática.

Valores singulares en el cuerpo¶

De la misma manera que hay unQuery yPath para definir datos extra para parámetros de query y path,FastAPI proporciona un equivalenteBody.

Por ejemplo, ampliando el modelo anterior, podrías decidir que deseas tener otra claveimportance en el mismo cuerpo, además deitem yuser.

Si lo declaras tal cual, debido a que es un valor singular,FastAPI asumirá que es un parámetro de query.

Pero puedes instruir aFastAPI para que lo trate como otra clave del cuerpo usandoBody:

fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=NoneclassUser(BaseModel):username:strfull_name:str|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item,user:User,importance:Annotated[int,Body()]):results={"item_id":item_id,"item":item,"user":user,"importance":importance}returnresults

fromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=NoneclassUser(BaseModel):username:strfull_name:str|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item,user:User,importance:int=Body()):results={"item_id":item_id,"item":item,"user":user,"importance":importance}returnresults

En este caso,FastAPI esperará un cuerpo como:

{"item":{"name":"Foo","description":"The pretender","price":42.0,"tax":3.2},"user":{"username":"dave","full_name":"Dave Grohl"},"importance":5}

Nuevamente, convertirá los tipos de datos, validará, documentará, etc.

Múltiples parámetros de cuerpo y query¶

Por supuesto, también puedes declarar parámetros adicionales de query siempre que lo necesites, además de cualquier parámetro del cuerpo.

Como, por defecto, los valores singulares se interpretan como parámetros de query, no tienes que añadir explícitamente unQuery, solo puedes hacer:

q:str|None=None

Por ejemplo:

fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=NoneclassUser(BaseModel):username:strfull_name:str|None=None@app.put("/items/{item_id}")asyncdefupdate_item(*,item_id:int,item:Item,user:User,importance:Annotated[int,Body(gt=0)],q:str|None=None,):results={"item_id":item_id,"item":item,"user":user,"importance":importance}ifq:results.update({"q":q})returnresults

fromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=NoneclassUser(BaseModel):username:strfull_name:str|None=None@app.put("/items/{item_id}")asyncdefupdate_item(*,item_id:int,item:Item,user:User,importance:int=Body(gt=0),q:str|None=None,):results={"item_id":item_id,"item":item,"user":user,"importance":importance}ifq:results.update({"q":q})returnresults

Embeber un solo parámetro de cuerpo¶

Supongamos que solo tienes un único parámetro de cuerpoitem de un modelo PydanticItem.

Por defecto,FastAPI esperará su cuerpo directamente.

Pero si deseas que espere un JSON con una claveitem y dentro de ella los contenidos del modelo, como lo hace cuando declaras parámetros de cuerpo extra, puedes usar el parámetro especialBodyembed:

item:Item=Body(embed=True)

como en:

fromtypingimportAnnotatedfromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Annotated[Item,Body(embed=True)]):results={"item_id":item_id,"item":item}returnresults

fromfastapiimportBody,FastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item=Body(embed=True)):results={"item_id":item_id,"item":item}returnresults

En este caso,FastAPI esperará un cuerpo como:

{"item":{"name":"Foo","description":"The pretender","price":42.0,"tax":3.2}}

en lugar de:

{"name":"Foo","description":"The pretender","price":42.0,"tax":3.2}

Resumen¶

Puedes añadir múltiples parámetros de cuerpo a tupath operation function, aunque un request solo puede tener un único cuerpo.

PeroFastAPI lo manejará, te dará los datos correctos en tu función, y validará y documentará el esquema correcto en lapath operation.

También puedes declarar valores singulares para ser recibidos como parte del cuerpo.

Y puedes instruir aFastAPI para embeber el cuerpo en una clave incluso cuando solo hay un único parámetro declarado.