OpenAPI para iniciantes: escreva seu primeiro contrato em 20 minutos

Se você desenvolve APIs mas nunca parou para escrever um openapi.yaml, é normal que a especificação pareça distante ou formal demais. Na prática, OpenAPI é apenas uma forma padrão de descrever como conversar com a sua API em um arquivo que tanto pessoas quanto ferramentas conseguem entender.

Neste tutorial você vai criar seu primeiro contrato OpenAPI do zero, entender o que cada bloco representa e ver como esse arquivo se transforma automaticamente em documentação navegável. Não é preciso conhecer todos os detalhes da especificação; com alguns conceitos básicos já dá para trabalhar de maneira muito mais organizada.

O que é OpenAPI (explicado de forma simples)

OpenAPI é um formato para descrever APIs HTTP em um arquivo (geralmente YAML ou JSON). Nesse arquivo você define coisas como:

Quais endpoints existem (por exemplo /tasks, /users).
Quais métodos eles aceitam (GET, POST, etc.).
Quais parâmetros esperam (query, path, headers, body).
Quais respostas retornam (códigos, modelos de dados, erros).
Como quem chama a API deve se autenticar.

Pense nisso como um “mapa técnico” da sua API. Esse mapa pode ser lido por pessoas, mas também por editores visuais, geradores de documentação, geradores de SDKs e ferramentas de teste. Por isso faz sentido investir alguns minutos para defini-lo bem: todo o resto fica muito mais fácil de automatizar.

A anatomia mínima de um arquivo OpenAPI

Um arquivo openapi.yaml básico costuma ter cinco seções importantes:

openapi: a versão da especificação que você está usando.
info: informações gerais da sua API (título, descrição, versão).
servers: URLs base onde a API está disponível.
paths: rotas e métodos concretos (/tasks, GET, POST, etc.).
components: modelos reutilizáveis (por exemplo, o esquema Task).

A partir daí você pode adicionar segurança, parâmetros globais, respostas comuns e muitos outros detalhes, mas não precisa de tudo isso para começar. Com uma estrutura mínima já é possível descrever uma API simples e visualizá-la como documentação.

Sua primeira API de exemplo: API de tarefas

Imagine que você quer documentar uma API bem simples com apenas um endpoint:

GET /tasks: retorna a lista de tarefas.

Vamos construir o openapi.yaml passo a passo. Primeiro, o cabeçalho com a versão, as informações básicas e o servidor:

openapi: 3.0.3
info:
  title: API de tarefas
  version: 1.0.0
  description: API de exemplo para gerenciar tarefas
servers:
  - url: https://api.exemplo.com

Agora vamos adicionar a rota /tasks com o método GET e uma resposta 200 que retorna um array de tarefas. Para isso, criaremos também um esquema Task em components.schemas:

openapi: 3.0.3
info:
  title: API de tarefas
  version: 1.0.0
  description: API de exemplo para gerenciar tarefas
servers:
  - url: https://api.exemplo.com
paths:
  /tasks:
    get:
      summary: Lista todas as tarefas
      description: Retorna todas as tarefas visíveis para o usuário autenticado.
      responses:
        '200':
          description: Lista de tarefas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: "Comprar leite"
        completed:
          type: boolean
          example: false

Com esse trecho você já está descrevendo:

Que existe um endpoint GET /tasks.
Que ele retorna um código 200 com um corpo application/json.
Que o corpo é um array de objetos Task.
Quais campos Task possui e qual é o tipo de cada um.

Ainda não definimos autenticação, erros nem outros endpoints, mas você já tem uma base útil para começar a compartilhar a API e gerar documentação.

Ver o seu spec como documentação visual

Uma das partes mais interessantes do OpenAPI é que você pode colar o openapi.yaml em um editor visual e obter um portal de documentação navegável sem escrever HTML. Ferramentas como Swagger Editor e outras alternativas online permitem:

Ver a lista de endpoints em um menu lateral.
Expandir cada operação para revisar parâmetros e respostas.
Testar chamadas diretamente do navegador se o servidor estiver configurado corretamente.

O fluxo básico fica assim:

Renderizando diagrama…

Ou seja: uma vez que você tem o contrato em OpenAPI, esse arquivo se torna a fonte de verdade que alimenta docs, testes, mocks e clientes. Não é mais necessário reescrever a mesma informação em vários lugares diferentes.

Além dos editores genéricos, você pode trabalhar diretamente no seu contrato dentro do Capydox: o workspace inclui um editor OpenAPI que funciona como um visualizador no estilo Swagger e permite importar um spec existente, gerar documentação mais rica e, se você já trabalha com coleções de testes, converter coleções em contratos OpenAPI ou o inverso (criar coleções a partir do seu swagger). Assim, contrato, documentação e evidências de teste ficam concentrados no mesmo lugar.

Por que faz sentido escrever OpenAPI mesmo em projetos pequenos

Pode parecer que OpenAPI é algo “pesado”, reservado para grandes empresas ou APIs públicas com muitos usuários. Na prática, projetos pequenos se beneficiam ainda mais:

Você evita esquecer detalhes: ao precisar definir parâmetros, modelos e respostas, você pensa melhor o desenho da API.
Você ajuda o seu "eu do futuro": quando voltar ao projeto meses depois, o contrato lembra como cada endpoint se comporta sem precisar ler todo o código.
Você abre espaço para automação: mesmo que no início use o spec apenas para gerar docs, mais tarde poderá adicionar validações em CI, mocks, SDKs e muito mais.

Em equipes, OpenAPI vira a linguagem comum entre backend, frontend, QA e qualquer integrador externo. Todos falam sobre a mesma coisa: o contrato.

Próximos passos e onde o Capydox entra

Com seu primeiro openapi.yaml funcionando, o próximo passo é integrar esse contrato ao seu fluxo normal de trabalho:

Versionar o arquivo junto com o código no Git.
Revisar mudanças de contrato via pull request, como qualquer alteração de código.
Adicionar checks automáticos para validar o spec antes do deploy.

A partir daí, você pode conectar ferramentas em torno desse contrato. O Capydox, por exemplo, pode usar seu arquivo OpenAPI como matéria-prima para gerar documentação mais rica, ligar essa doc a evidências de testes e ajudar a manter tudo alinhado com o que realmente está rodando nos seus ambientes.

A ideia de fundo é simples: quanto antes você transformar a sua API em um contrato explícito, mais fácil será documentá-la, testá-la e evoluí-la sem surpresas.

OpenAPI para iniciantes: escreva seu primeiro contrato em 20 minutos