Mas a documentação ainda está faltando. Então APISpec foi criado.

APISpec tem plug-ins para muitos frameworks (e tem um plug-in para Starlette também).

O jeito como ele funciona é que você escreve a definição do _schema_ usando formato YAML dentro da _docstring_ de cada função controlando uma rota.

E ele gera _schemas_ OpenAPI.

É assim como funciona no Flask, Starlette, Responder etc.

```mermaid
graph TB

common_parameters(["common_parameters"])
read_items["/items/"]
read_users["/users/"]

common_parameters --> read_items
common_parameters --> read_users
```

Assim, você escreve um código compartilhado apenas uma vez e o **FastAPI** se encarrega de chamá-lo em suas *operações de rota*.

/// check | Checando

Se você precisa refrescar a memória rapidamente sobre como usar tipos do Python (mesmo que você não use o FastAPI), confira esse rápido tutorial: [Tipos do Python](python-types.md){.internal-link target=_blank}.

Você escreve Python padrão com tipos:

```Python
from datetime import date

from pydantic import BaseModel

# Declare uma variável como str
# e obtenha suporte do editor dentro da função
def main(user_id: str):

Isso está em contraste às funções que o FastAPI chama para você: *funções de operação de rota* e dependências.

Se sua função de utilidade é uma função normal com `def`, ela será chamada diretamente (como você a escreve no código), não em uma threadpool, se a função é criada com `async def` então você deve esperar por essa função quando você chamá-la no seu código.

---

### O que é um Programa

A palavra **programa** é comumente usada para descrever muitas coisas:

* O **código** que você escreve, os **arquivos Python**.
* O **arquivo** que pode ser **executado** pelo sistema operacional, por exemplo: `python`, `python.exe` ou `uvicorn`.

## Recapitulando

* Importe `FastAPI`.
* Crie uma instância do `app`.
* Coloque o **decorador que define a operação** (como `@app.get("/")`).
* Escreva uma **função para a operação da rota** (como `def root(): ...`) abaixo.

/// tip | Dica

Fazer com que o modelo de retorno garanta que um valor esteja sempre disponível e sempre seja um `int` (não `None`) é muito útil para os clientes da API, eles podem escrever código muito mais simples com essa certeza.

Para fazer isso, utilize `yield` em vez de `return`, e escreva os passos extras (código) depois.

/// tip | Dica

Garanta que `yield` é utilizado apenas uma vez.

///

/// note | Detalhes Técnicos

Qualquer função que possa ser utilizada com:

## Recapitulación

* Importa `FastAPI`.
* Crea una instancia `app`.
* Escribe un **path operation decorator** usando decoradores como `@app.get("/")`.
* Define una **path operation function**; por ejemplo, `def root(): ...`.

Para hacer esto, usa `yield` en lugar de `return` y escribe los pasos adicionales (código) después.

/// tip | Consejo

Asegúrate de usar `yield` una sola vez por dependencia.

///

/// note | Nota técnica

Cualquier función que sea válida para usar con: