OpenAPI é um formato padronizado para descrever uma API HTTP: endpoints, parâmetros, formatos de resposta, autenticação e erros. É um contrato legível por máquina — e é isso que o torna útil.
O que dá para fazer com a especificação
- Importar a coleção completa no Postman ou Insomnia em segundos.
- Gerar clientes automaticamente em várias linguagens.
- Validar em teste que a resposta da API bate com o contrato.
- Alimentar ferramentas de IA com o contrato exato da API, evitando código inventado.
JSON ou YAML
São o mesmo conteúdo em formatos diferentes. JSON costuma ser preferido por ferramentas; YAML é mais fácil de ler. A Pitra publica os dois.
Versionamento
A especificação deve ter versão própria e mudar junto com a API. Se a documentação diz uma coisa e a especificação outra, o contrato perdeu o valor.
Perguntas frequentes
- OpenAPI substitui a documentação?
- Não. Ela cobre o contrato técnico; guias, conceitos e exemplos continuam necessários.