Então vamos usar esse mesmo conhecimento para documentar como a *API externa* deveria ser... criando as *operações de rota* que a *API externa* deveria implementar (as que sua API irá chamar).

/// tip | Dica

Ao escrever o código para documentar um callback, pode ser útil imaginar que você é aquele *desenvolvedor externo*. E que você está atualmente implementando a *API externa*, não *sua API*.

Você pode defini-los da seguinte maneira:

{* ../../docs_src/metadata/tutorial001_py310.py hl[3:16, 19:32] *}

/// tip | Dica

Você pode escrever Markdown no campo `description` e ele será renderizado na saída.

///

Com essa configuração, a documentação automática da API se pareceria com:

<img src="/img/tutorial/metadata/image01.png">

Nos exemplos acima, você pode ver que existe uma pequena **duplicação de código**.

Quando você precisa utilizar a dependência `common_parameters()`, você precisa escrever o parâmetro inteiro com uma anotação de tipo e `Depends()`:

```Python
commons: Annotated[dict, Depends(common_parameters)]
```

/// 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.

Tenha em mente que, como os chats permitem uma “conversa mais livre”, é fácil fazer perguntas muito gerais e mais difíceis de responder, então você pode acabar não recebendo respostas.

Por exemplo, para declarar um parâmetro de consulta `q` que pode aparecer várias vezes na URL, você pode escrever:

{* ../../docs_src/query_params_str_validations/tutorial011_an_py310.py hl[9] *}

Então, com uma URL como:

```
http://localhost:8000/items/?q=foo&q=bar
```

É uma grande ferramenta, muito subestimada. Deveria ser bem mais popular do que muitos plug-ins Flask por aí. Pode ser devido à sua documentação ser concisa e abstrata demais.

Isso resolveu ter que escrever YAML (outra sintaxe) dentro das docstrings do Python.

Essa combinação de Flask, Flask-apispec com Marshmallow e Webargs foi a minha stack de backend favorita até construir o **FastAPI**.

É apenas uma função padrão que pode receber parâmetros.

Pode ser uma função `async def` ou um `def` normal, o **FastAPI** saberá como lidar com isso corretamente.

Neste caso, a função da tarefa escreverá em um arquivo (simulando o envio de um e-mail).

E como a operação de escrita não usa `async` e `await`, definimos a função com um `def` normal:

{* ../../docs_src/background_tasks/tutorial001_py310.py hl[6:9] *}

Toda a **lógica** sobre como cadastrar as URLs para os webhooks e o código para enviar de fato as requisições cabe a você definir. Você escreve da maneira que você desejar no **seu próprio código**.

## Documentando webhooks com o **FastAPI** e OpenAPI { #documenting-webhooks-with-fastapi-and-openapi }

### O que é um Programa { #what-is-a-program }

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`.