En este caso, podrías querer documentar cómo esa API externa *debería* verse. Qué *path operation* debería tener, qué cuerpo debería esperar, qué response debería devolver, etc.

## Una aplicación con callbacks

Veamos todo esto con un ejemplo.

Imagina que desarrollas una aplicación que permite crear facturas.

código do cliente automaticamente. E se você **construir** o cliente, ele dará erro se houver alguma **incompatibilidade** nos dados usados.

Então, você **detectaria vários erros** muito cedo no ciclo de desenvolvimento, em vez de ter que esperar que os erros apareçam para seus usuários finais em produção e então tentar depurar onde está o problema. ✨...

también puedes declarar un grupo de `examples` con información adicional que se añadirá a sus **JSON Schemas** dentro de **OpenAPI**.

### `Body` con `examples`

Aquí pasamos `examples` que contiene un ejemplo de los datos esperados en `Body()`:

{* ../../docs_src/schema_extra_example/tutorial003_an_py310.py hl[22:29] *}

### Ejemplo en la interfaz de documentación

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

De hecho, puedes omitir ese header extra y aún funcionaría.

Pero se proporciona aquí para cumplir con las especificaciones.

Además, podría haber herramientas que lo esperen y lo usen (ahora o en el futuro) y eso podría ser útil para ti o tus usuarios, ahora o en el futuro.

Ese es el beneficio de los estándares...

///

## Verlo en acción

Sin embargo, podemos declarar el esquema esperado para el cuerpo del request.

### Tipo de contenido personalizado de OpenAPI

De toda forma, nós podemos declarar o esquema esperado para o corpo da requisição.

### Tipo de conteúdo do OpenAPI personalizado

automáticamente en el código del cliente. Y si haces **build** del cliente, te dará error si tienes algún **desajuste** en los datos utilizados.

Así que, **detectarás muchos errores** muy temprano en el ciclo de desarrollo en lugar de tener que esperar a que los errores se muestren a tus usuarios finales en producción para luego intentar depurar dónde está el problema. ✨...

constraints.DecimalMax.message = {item} deve ser menor que {value}.
constraints.DecimalMin.message = {item} deve ser maior que {value}.
constraints.Digits.message = {item} deve ser um número. (Esperado: <número>.<número>)
constraints.Future.message = {item} deve ser uma data futura.
constraints.Max.message = {item} deve ser menor ou igual a {value}.
constraints.Min.message = {item} deve ser maior ou igual a {value}.

Finalmente, a identidade dos nossos heróis está protegida! 🥷

Ele também declara novamente `id: int`. Ao fazer isso, estamos fazendo um **contrato** com os clientes da API, para que eles possam sempre esperar que o `id` estará lá e será um `int` (nunca será `None`).

/// tip | Dica

Na verdade, você pode pular esse cabeçalho extra e ainda funcionaria.

Mas é fornecido aqui para estar em conformidade com as especificações.

Além disso, pode haver ferramentas que esperam e usam isso (agora ou no futuro) e que podem ser úteis para você ou seus usuários, agora ou no futuro.

Esse é o benefício dos padrões...

///

## Veja em ação