Pular para o conteúdo
Criação de Apps

OpenAPI: como documentar uma API e por que isso evita retrabalho

Resposta rápida

OpenAPI é uma especificação aberta, escrita em YAML ou JSON, que descreve os endereços, parâmetros, respostas e erros de uma API. Com esse arquivo, ferramentas geram documentação navegável, exemplos de chamada e até testes. Quanto mais cedo você escreve, menos mal-entendidos surgem entre quem constrói e quem usa a API.

Neste artigo
  1. O que vai dentro do arquivo
  2. Um exemplo em palavras
  3. O que você ganha
  4. Como começar sem travar

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

  1. Escolha dois ou três endereços mais usados e documente só esses.
  2. Escreva os exemplos de resposta com dados realistas, mas sem informação de pessoas reais.
  3. Valide o arquivo num editor online ou numa ferramenta de linha de comando para pegar erros de formato.
  4. 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.

  • API
  • OpenAPI
  • Documentação
  • Desenvolvimento

Perguntas frequentes

OpenAPI e Swagger são a mesma coisa?

Swagger é o nome histórico da especificação e hoje também designa um conjunto de ferramentas. A especificação em si se chama OpenAPI.

Preciso escrever o arquivo à mão?

Pode escrever à mão ou gerar a partir do código, dependendo do framework. Em ambos os casos, revise o resultado para garantir que descreve o que a API realmente faz.

Leia também

Criação de Apps

Versionamento semântico: como numerar as versões do seu app

Os três números de uma versão contam, de forma padronizada, o tamanho da mudança que chegou.

· 2 min de leitura
Criação de Apps

O que é API e para que serve, explicado sem complicação

A ideia por trás das APIs com exemplos do dia a dia, termos explicados e um primeiro teste prático.

· 5 min de leitura
Criação de Apps

REST ou GraphQL: como escolher o estilo de API para o seu app

REST e GraphQL resolvem o mesmo problema de jeitos diferentes, e a escolha depende do seu app.

· 3 min de leitura
Criação de Apps

Monolito ou microsserviços: qual arquitetura escolher no seu app

Dividir o sistema em muitos serviços resolve alguns problemas e cria outros.

· 2 min de leitura

Deixe seu comentário