Quando uma API passa de duas pessoas, o conhecimento que estava na cabeça de quem a criou vira fonte de dúvida: qual campo é obrigatório? O que volta quando dá erro? OpenAPI resolve isso com um arquivo único que descreve tudo de forma que pessoas e programas entendam.
Se você ainda está firmando o conceito de API, comece por o que é API e para que serve.
O que vai dentro do arquivo
Um documento OpenAPI costuma ter quatro blocos:
- Informações gerais: nome da API, versão e descrição.
- Servidores: os endereços base onde a API responde, como o de testes e o de produção.
- Caminhos: cada endereço, com o método aceito (GET, POST e assim por diante), os parâmetros e as respostas possíveis.
- Componentes: modelos reutilizáveis, como o formato de um pedido ou de um erro, para não repetir a mesma descrição dez vezes.
Um exemplo em palavras
Imagine uma API de pedidos. No arquivo, você declara o caminho /pedidos/{id} com o método GET e o resumo "Busca um pedido pelo número". Em seguida, descreve o parâmetro id: ele vai no caminho, é obrigatório e é um número inteiro. Por fim, lista as respostas: código 200 para pedido encontrado e código 404 para pedido inexistente.
Na primeira linha do arquivo vai a versão da especificação usada, e o campo info leva o título e a versão da sua API. A versão vigente da especificação está no site oficial do OpenAPI Initiative.
O que você ganha
- Documentação navegável: ferramentas como o Swagger UI transformam o arquivo numa página onde dá para ler e testar cada chamada.
- Menos dúvida: quem consome sabe os campos, os tipos e os códigos de erro sem perguntar.
- Geração de código: há ferramentas que criam clientes em várias linguagens a partir do arquivo.
- Contrato claro: se o código muda e o arquivo não, a diferença aparece na revisão.
Como começar sem travar
- Escolha dois ou três endereços mais usados e documente só esses.
- Escreva os exemplos de resposta com dados realistas, mas sem informação de pessoas reais.
- Valide o arquivo num editor online ou numa ferramenta de linha de comando para pegar erros de formato.
- Guarde o arquivo no mesmo repositório do código e atualize junto com cada mudança. A prática combina bem com versionamento semântico.
Documentar a API não precisa ser projeto à parte: um arquivo curto, mantido junto do código, já tira a maior parte da confusão.