Declarar Ejemplos de Request¶

Puedes declarar ejemplos de los datos que tu aplicación puede recibir.

Aquí tienes varias formas de hacerlo.

Datos extra de JSON Schema en modelos de Pydantic¶

Puedes declararexamples para un modelo de Pydantic que se añadirá al JSON Schema generado.

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonemodel_config={"json_schema_extra":{"examples":[{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,}]}}@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Esa información extra se añadirá tal cual alJSON Schema resultante para ese modelo, y se usará en la documentación de la API.

Puedes usar el atributomodel_config que toma undict como se describe enla documentación de Pydantic: Configuración.

Puedes establecer"json_schema_extra" con undict que contenga cualquier dato adicional que te gustaría que aparezca en el JSON Schema generado, incluyendoexamples.

Argumentos adicionales enField¶

Cuando usasField() con modelos de Pydantic, también puedes declararexamples adicionales:

fromfastapiimportFastAPIfrompydanticimportBaseModel,Fieldapp=FastAPI()classItem(BaseModel):name:str=Field(examples=["Foo"])description:str|None=Field(default=None,examples=["A very nice Item"])price:float=Field(examples=[35.4])tax:float|None=Field(default=None,examples=[3.2])@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

examples en JSON Schema - OpenAPI¶

Cuando usas cualquiera de:

• Path()
• Query()
• Header()
• Cookie()
• Body()
• Form()
• File()

también puedes declarar un grupo deexamples con información adicional que se añadirá a susJSON Schemas dentro deOpenAPI.

Body conexamples¶

Aquí pasamosexamples que contiene un ejemplo de los datos esperados enBody():

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(examples=[{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,}],),],):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(examples=[{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,}],),):results={"item_id":item_id,"item":item}returnresults

Ejemplo en la interfaz de documentación¶

Con cualquiera de los métodos anteriores se vería así en los/docs:

Body con múltiplesexamples¶

Por supuesto, también puedes pasar múltiplesexamples:

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(examples=[{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,},{"name":"Bar","price":"35.4",},{"name":"Baz","price":"thirty five point four",},],),],):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(examples=[{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,},{"name":"Bar","price":"35.4",},{"name":"Baz","price":"thirty five point four",},],),):results={"item_id":item_id,"item":item}returnresults

Cuando haces esto, los ejemplos serán parte delJSON Schema interno para esos datos del body.

Sin embargo, almomento de escribir esto, Swagger UI, la herramienta encargada de mostrar la interfaz de documentación, no soporta mostrar múltiples ejemplos para los datos enJSON Schema. Pero lee más abajo para una solución alternativa.

examples específicos de OpenAPI¶

Desde antes de queJSON Schema soportaraexamples, OpenAPI tenía soporte para un campo diferente también llamadoexamples.

Estosexamples específicos deOpenAPI van en otra sección en la especificación de OpenAPI. Van en losdetalles para cadapath operation, no dentro de cada JSON Schema.

Y Swagger UI ha soportado este campo particular deexamples por un tiempo. Así que, puedes usarlo paramostrar diferentesejemplos en la interfaz de documentación.

La forma de este campo específico de OpenAPIexamples es undict conmúltiples ejemplos (en lugar de unalist), cada uno con información adicional que también se añadirá aOpenAPI.

Esto no va dentro de cada JSON Schema contenido en OpenAPI, esto va afuera, directamente en lapath operation.

Usando el Parámetroopenapi_examples¶

Puedes declarar losexamples específicos de OpenAPI en FastAPI con el parámetroopenapi_examples para:

• Path()
• Query()
• Header()
• Cookie()
• Body()
• Form()
• File()

Las claves deldict identifican cada ejemplo, y cada valor es otrodict.

Cadadict específico del ejemplo en losexamples puede contener:

• summary: Descripción corta del ejemplo.
• description: Una descripción larga que puede contener texto Markdown.
• value: Este es el ejemplo real mostrado, e.g. undict.
• externalValue: alternativa avalue, una URL que apunta al ejemplo. Aunque esto puede no ser soportado por tantas herramientas comovalue.

Puedes usarlo así:

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(openapi_examples={"normal":{"summary":"A normal example","description":"A **normal** item works correctly.","value":{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,},},"converted":{"summary":"An example with converted data","description":"FastAPI can convert price `strings` to actual `numbers` automatically","value":{"name":"Bar","price":"35.4",},},"invalid":{"summary":"Invalid data is rejected with an error","value":{"name":"Baz","price":"thirty five point four",},},},),],):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(openapi_examples={"normal":{"summary":"A normal example","description":"A **normal** item works correctly.","value":{"name":"Foo","description":"A very nice Item","price":35.4,"tax":3.2,},},"converted":{"summary":"An example with converted data","description":"FastAPI can convert price `strings` to actual `numbers` automatically","value":{"name":"Bar","price":"35.4",},},"invalid":{"summary":"Invalid data is rejected with an error","value":{"name":"Baz","price":"thirty five point four",},},},),):results={"item_id":item_id,"item":item}returnresults

Ejemplos de OpenAPI en la Interfaz de Documentación¶

Conopenapi_examples añadido aBody(), los/docs se verían así:

Detalles Técnicos¶

Antes de OpenAPI 3.1.0, OpenAPI usaba una versión más antigua y modificada deJSON Schema.

JSON Schema no teníaexamples, así que OpenAPI añadió su propio campoexample a su versión modificada.

OpenAPI también añadió los camposexample yexamples a otras partes de la especificación:

• Parameter Object (en la especificación) que era usado por FastAPI:
  • Path()
  • Query()
  • Header()
  • Cookie()
• Request Body Object, en el campocontent, sobre elMedia Type Object (en la especificación) que era usado por FastAPI:
  • Body()
  • File()
  • Form()

Campoexamples de JSON Schema¶

Pero luego JSON Schema añadió uncampoexamples a una nueva versión de la especificación.

Y entonces el nuevo OpenAPI 3.1.0 se basó en la última versión (JSON Schema 2020-12) que incluía este nuevo campoexamples.

Y ahora este nuevo campoexamples tiene precedencia sobre el viejo campo único (y personalizado)example, que ahora está obsoleto.

Este nuevo campoexamples en JSON Schema essolo unalist de ejemplos, no un dict con metadatos adicionales como en los otros lugares en OpenAPI (descritos arriba).

examples de Pydantic y FastAPI¶

Cuando añadesexamples dentro de un modelo de Pydantic, usandoschema_extra oField(examples=["something"]), ese ejemplo se añade alJSON Schema para ese modelo de Pydantic.

Y eseJSON Schema del modelo de Pydantic se incluye en elOpenAPI de tu API, y luego se usa en la interfaz de documentación.

En las versiones de FastAPI antes de 0.99.0 (0.99.0 y superiores usan el nuevo OpenAPI 3.1.0) cuando usabasexample oexamples con cualquiera de las otras utilidades (Query(),Body(), etc.) esos ejemplos no se añadían al JSON Schema que describe esos datos (ni siquiera a la propia versión de JSON Schema de OpenAPI), se añadían directamente a la declaración de lapath operation en OpenAPI (fuera de las partes de OpenAPI que usan JSON Schema).

Pero ahora que FastAPI 0.99.0 y superiores usa OpenAPI 3.1.0, que usa JSON Schema 2020-12, y Swagger UI 5.0.0 y superiores, todo es más consistente y los ejemplos se incluyen en JSON Schema.

Swagger UI yexamples específicos de OpenAPI¶

Ahora, como Swagger UI no soportaba múltiples ejemplos de JSON Schema (a fecha de 2023-08-26), los usuarios no tenían una forma de mostrar múltiples ejemplos en la documentación.

Para resolver eso, FastAPI0.103.0añadió soporte para declarar el mismo viejo campoespecífico de OpenAPIexamples con el nuevo parámetroopenapi_examples. 🤓

Resumen¶

Solía decir que no me gustaba mucho la historia... y mírame ahora dando lecciones de "historia tecnológica". 😅

En resumen,actualiza a FastAPI 0.99.0 o superior, y las cosas son muchomás simples, consistentes e intuitivas, y no necesitas conocer todos estos detalles históricos. 😎