Separación de Esquemas OpenAPI para Entrada y Salida o No¶

Desde que se lanzóPydantic v2, el OpenAPI generado es un poco más exacto ycorrecto que antes. 😎

De hecho, en algunos casos, incluso tendrádos JSON Schemas en OpenAPI para el mismo modelo Pydantic, para entrada y salida, dependiendo de si tienenvalores por defecto.

Veamos cómo funciona eso y cómo cambiarlo si necesitas hacerlo.

Modelos Pydantic para Entrada y Salida¶

Digamos que tienes un modelo Pydantic con valores por defecto, como este:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=None# Code below omitted 👇

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneapp=FastAPI()@app.post("/items/")defcreate_item(item:Item):returnitem@app.get("/items/")defread_items()->list[Item]:return[Item(name="Portal Gun",description="Device to travel through the multi-rick-verse",),Item(name="Plumbus"),]

Modelo para Entrada¶

Si usas este modelo como entrada, como aquí:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneapp=FastAPI()@app.post("/items/")defcreate_item(item:Item):returnitem# Code below omitted 👇

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneapp=FastAPI()@app.post("/items/")defcreate_item(item:Item):returnitem@app.get("/items/")defread_items()->list[Item]:return[Item(name="Portal Gun",description="Device to travel through the multi-rick-verse",),Item(name="Plumbus"),]

...entonces el campodescriptionno será requerido. Porque tiene un valor por defecto deNone.

Modelo de Entrada en la Documentación¶

Puedes confirmar eso en la documentación, el campodescription no tiene unasterisco rojo, no está marcado como requerido:

Modelo para Salida¶

Pero si usas el mismo modelo como salida, como aquí:

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneapp=FastAPI()@app.post("/items/")defcreate_item(item:Item):returnitem@app.get("/items/")defread_items()->list[Item]:return[Item(name="Portal Gun",description="Device to travel through the multi-rick-verse",),Item(name="Plumbus"),]

...entonces, porquedescription tiene un valor por defecto, sino devuelves nada para ese campo, aún tendrá esevalor por defecto.

Modelo para Datos de Response de Salida¶

Si interactúas con la documentación y revisas el response, aunque el código no agregó nada en uno de los camposdescription, el response JSON contiene el valor por defecto (null):

Esto significa quesiempre tendrá un valor, solo que a veces el valor podría serNone (onull en JSON).

Eso significa que, los clientes que usan tu API no tienen que revisar si el valor existe o no, puedenasumir que el campo siempre estará allí, pero solo que en algunos casos tendrá el valor por defecto deNone.

La forma de describir esto en OpenAPI es marcar ese campo comorequerido, porque siempre estará allí.

Debido a eso, el JSON Schema para un modelo puede ser diferente dependiendo de si se usa paraentrada o salida:

• paraentrada eldescriptionno será requerido
• parasalida serárequerido (y posiblementeNone, o en términos de JSON,null)

Modelo para Salida en la Documentación¶

También puedes revisar el modelo de salida en la documentación,ambosname ydescription están marcados comorequeridos con unasterisco rojo:

Modelo para Entrada y Salida en la Documentación¶

Y si revisas todos los esquemas disponibles (JSON Schemas) en OpenAPI, verás que hay dos, unoItem-Input y unoItem-Output.

ParaItem-Input,descriptionno es requerido, no tiene un asterisco rojo.

Pero paraItem-Output,descriptiones requerido, tiene un asterisco rojo.

Con esta funcionalidad dePydantic v2, la documentación de tu API es másprecisa, y si tienes clientes y SDKs autogenerados, también serán más precisos, con una mejorexperiencia para desarrolladores y consistencia. 🎉

No Separar Esquemas¶

Ahora, hay algunos casos donde podrías querer tener elmismo esquema para entrada y salida.

Probablemente el caso principal para esto es si ya tienes algún código cliente/SDKs autogenerado y no quieres actualizar todo el código cliente/SDKs autogenerado aún, probablemente querrás hacerlo en algún momento, pero tal vez no ahora.

En ese caso, puedes desactivar esta funcionalidad enFastAPI, con el parámetroseparate_input_output_schemas=False.

fromfastapiimportFastAPIfrompydanticimportBaseModelclassItem(BaseModel):name:strdescription:str|None=Noneapp=FastAPI(separate_input_output_schemas=False)@app.post("/items/")defcreate_item(item:Item):returnitem@app.get("/items/")defread_items()->list[Item]:return[Item(name="Portal Gun",description="Device to travel through the multi-rick-verse",),Item(name="Plumbus"),]

Mismo Esquema para Modelos de Entrada y Salida en la Documentación¶

Y ahora habrá un único esquema para entrada y salida para el modelo, soloItem, y tendrádescription comono requerido: