* **Documentar** a API usando OpenAPI:
    * que é usado pelas interfaces de usuário da documentação interativa automática.

Tudo isso pode parecer abstrato. Não se preocupe. Você verá tudo isso em ação no [Tutorial - Guia do usuário](tutorial/index.md){.internal-link target=_blank}.

Dessa forma eu pude encontrar a melhor maneira de reduzir duplicação de código o máximo possível, ter preenchimento automático em todos os lugares, conferência de tipos e erros etc.

Tudo de uma forma que oferecesse a melhor experiência de desenvolvimento para todos os desenvolvedores.

## Requisitos { #requirements }

* **`200 - 299`** são para respostas "Bem-sucedidas". Estes são os que você mais usaria.
    * `200` é o código de status padrão, o que significa que tudo estava "OK".
    * Outro exemplo seria `201`, "Criado". É comumente usado após a criação de um novo registro no banco de dados.

E eles podem tentar de novo sabendo que provavelmente é algo mais parecido com `stanleyjobsox` do que com `johndoe`.

#### Um ataque "profissional" { #a-professional-attack }

Claro, os invasores não tentariam tudo isso de forma manual, eles escreveriam um programa para fazer isso, possivelmente com milhares ou milhões de testes por segundo. E obteriam apenas uma letra a mais por vez.

* Definir uma lógica compartilhada (mesmo formato de código repetidamente).
* Compartilhar conexões com banco de dados.
* Aplicar regras de segurança, autenticação, papéis de usuários, etc.
* E muitas outras coisas...

Tudo isso, enquanto minimizamos a repetição de código.

## Primeiros passos { #first-steps }

Vamos ver um exemplo simples. Tão simples que não será muito útil, por enquanto.

Até aqui, tudo funcionaria normalmente.

Mas então, quando você abre a interface de documentação integrada (o frontend), ela esperaria obter o OpenAPI schema em `/openapi.json`, em vez de `/api/v1/openapi.json`.

Consiste apenas de funções que parecem idênticas a *funções de operação de rota*.

Mas ainda assim, é bastante poderoso, e permite que você declare grafos (árvores) de dependências com uma profundidade arbitrária.

/// tip | Dica

Tudo isso pode não parecer muito útil com esses exemplos.

Mas você verá o quão útil isso é nos capítulos sobre **segurança**.

E você também verá a quantidade de código que você não precisara escrever.

http://127.0.0.1:8000/items/foo?short=true
```

ou

```
http://127.0.0.1:8000/items/foo?short=on
```

ou

```
http://127.0.0.1:8000/items/foo?short=yes
```

ou qualquer outra variação (tudo em maiúscula, primeira letra em maiúscula, etc), a sua função vai ver o parâmetro `short` com um valor `bool` de `True`. Caso contrário `False`.

## Múltiplos parâmetros de rota e consulta { #multiple-path-and-query-parameters }

### Short { #short }

It has sensible **defaults** for everything, with optional configurations everywhere. All the parameters can be fine-tuned to do what you need and to define the API you need.

But by default, it all **"just works"**.

### Validation { #validation }

* Validation for most (or all?) Python **data types**, including:

    * Verifica que tem an atributo opcional `is_offer`, que deve ser `bool`, se presente.
    * Tudo isso também funciona para objetos JSON profundamente aninhados.
* Converter de e para JSON automaticamente.
* Documentar tudo com OpenAPI, que poderá ser usado por:
    * Sistemas de documentação interativos.
    * Sistemas de clientes de geração de código automáticos, para muitas linguagens.