Documentação e OpenAPI
O contrato da API como arquivo versionado, de onde saem documentação, clientes e testes.
OpenAPI é um formato padrão para descrever uma API HTTP num arquivo: as rotas, os parâmetros, os corpos, as respostas e os erros.
Esse arquivo é o contrato entre quem oferece e quem usa a API. Dele saem a documentação, os clientes gerados e os testes. Mas ele só vale enquanto descreve o que a API faz de verdade.
- O arquivo pode nascer do código ou ser escrito antes dele.
- A especificação gerada pelo código pode divergir do próprio código.
- Um teste de contrato envia pedidos à API e confere as respostas com o arquivo.
- Comparar duas versões do arquivo revela mudanças incompatíveis antes do deploy.