Como Versionar Especificações OpenAPI com Git: Guia Completo

Sua especificação OpenAPI é um contrato. Quando ela se desvia, os clientes quebram, os mocks ficam desatualizados e os testes passam contra uma API que não existe mais. Então, trate a especificação como o resto do seu código: coloque-a no Git, crie um branch, revise-a e valide-a a cada alteração.

Este guia detalha o controle de versão OpenAPI com Git do zero. Onde o arquivo reside, como criar branches, o que os revisores realmente procuram em um diff de especificação e como enviar alterações diretamente do Apidog. Ao final, você terá um fluxo de trabalho em que toda a sua equipe pode confiar.

Por que controlar a versão da sua especificação OpenAPI

Uma especificação que reside em uma wiki ou em um drive compartilhado não tem histórico. Você não consegue ver quem alterou o payload de POST /orders na última terça-feira, ou por quê. O Git resolve isso.

Coloque openapi.yaml sob controle de versão e você ganha quatro coisas de graça:

• Histórico. Toda alteração é um commit com um autor, um carimbo de data/hora e uma mensagem.
• Culpa (Blame). git blame openapi.yaml mostra quem adicionou aquele campo obrigatório e quando.
• Reversão. Uma fusão (merge) ruim que quebrou o contrato? Reverta o commit e você volta a ter uma especificação funcionando.
• Revisão. Alterações na especificação passam por pull requests, então uma segunda pessoa vê o diff antes de ser implantado.

Esta é a base de um fluxo de trabalho de API Git-nativo: a especificação é código-fonte, e código-fonte vive no Git.

Onde o arquivo de especificação vive no repositório

Mantenha-o simples e previsível. A maioria das equipes coloca um único openapi.yaml na raiz do repositório ou em uma pasta api/:

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

Quando você mantém várias versões principais em paralelo, divida por versão com um arquivo por principal:

api/
├── api-v1.yaml
└── api-v2.yaml

Isso mantém as alterações que quebram a compatibilidade isoladas. api-v1.yaml permanece congelado para clientes existentes enquanto api-v2.yaml evolui. Também torna os diffs menores e a revisão mais rápida, porque cada arquivo muda por um motivo. Tratar a especificação dessa forma é a ideia central por trás de 'API spec as code' (Especificação de API como código).

Escolha uma convenção e documente-a. O pior resultado é ter dois arquivos alegando ser “a” especificação.

Estratégias de branching para alterações na especificação

Você não precisa de um modelo de branching especial para especificações. Reutilize o que seu código já faz. Crie um branch a partir de main, faça a alteração, abra um PR.

convenção de nomenclatura que mantém os branches de especificação fáceis de analisar:

O prefixo api/ sinaliza “este PR afeta o contrato” à primeira vista. Revisores e CI podem filtrar por ele. Para alterações que quebram a compatibilidade, o prefixo explícito breaking- é uma bandeira de que isso precisa de atenção extra e provavelmente um aumento de versão.

Mantenha os branches de curta duração. Um branch de especificação que vive por duas semanas colidirá com as alterações de todos os outros. Branches pequenos e focados se fundem (merge) de forma limpa.

Revisando alterações na especificação em um pull request

É aqui que o controle de versão mostra o seu valor. Um PR de especificação é uma alteração de contrato, e alterações de contrato merecem uma revisão real.

Escreva YAML de uma forma amigável para diffs, para que os revisores possam ler a alteração, não lutar com a formatação:

paths:
 /orders/{orderId}:
 get:
 summary: Get an order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: Order found
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

Identação consistente e uma propriedade por linha significam que a adição de um único campo aparece como um diff de uma única linha. Esse é o objetivo.

O que os revisores devem verificar:

• Alterações que quebram a compatibilidade. Um campo obrigatório foi adicionado a uma requisição? Um campo de resposta foi removido ou renomeado? Um enum perdeu um valor? Cada uma dessas coisas pode quebrar clientes existentes.
• Compatibilidade retroativa. Novos campos opcionais e novos endpoints são seguros. Alterações em formatos existentes não são.
• Nomenclatura e consistência. O novo endpoint corresponde à capitalização e pluralização do resto da API?
• Completeza. Toda nova operação precisa de um summary, schemas de resposta e respostas de erro.
• Exemplos. Exemplos realistas tornam a documentação e os mocks úteis.

Para detecção de alterações que quebram a compatibilidade, confie em ferramentas em vez de apenas na observação manual. Uma etapa de CI (abordada abaixo) pode comparar a especificação do PR com a main e falhar a build se detectar uma alteração incompatível. Humanos perdem isso; ferramentas de diff não.

Commit e push do Apidog

Editar YAML bruto manualmente funciona, mas um editor visual com validação em tempo real é mais rápido e detecta erros mais cedo. O Modo Spec-First do Apidog oferece sincronização Git bidirecional: edite a especificação na UI, faça commit e envie (push) para o seu repositório sem sair da ferramenta. Puxe as alterações de um colega de equipe da mesma forma.O fluxo é assim:

1. Conecte seu repositório Git e aponte o Apidog para o arquivo de especificação.
2. Edite endpoints, schemas e exemplos no editor visual.
3. O Apidog escreve YAML limpo e amigável para diffs de volta ao arquivo.
4. Faça commit em um branch e envie (push), então abra seu PR como de costume.

Como o Apidog serializa o YAML de forma consistente, seus diffs permanecem pequenos e revisáveis, sem reordenações ou reformatações ruidosas. Você pode ler a configuração completa na documentação do Modo Spec-First do Apidog. Se você quiser que o arquivo seja direcionado a um provedor específico, consulte a sincronização da sua especificação OpenAPI com o GitHub.

Ganchos de validação de CI

Nunca permita que uma especificação inválida chegue à main. Integre a validação nas suas verificações de pull request para que um contrato quebrado falhe a build automaticamente.

Uma etapa mínima do GitHub Actions:

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

Adicione mais verificações à medida que você cresce:

• Faça o lint da especificação para problemas estruturais e de estilo.
• Valide se ela é parseada como OpenAPI 3.x legal.
• Faça diff com a main para detectar alterações que quebram a compatibilidade e sinalizá-las no PR.

Essas verificações são executadas em segundos e capturam os erros que um revisor humano poderia ignorar.

Melhores práticas

Alguns hábitos mantêm o controle de versão da especificação saudável ao longo do tempo:

• Use versionamento semântico. Aumente o campo info.version. Uma alteração que quebra a compatibilidade significa uma nova versão principal; adições retrocompatíveis aumentam a versão secundária.
• Mantenha um changelog. Um CHANGELOG.md curto ao lado da especificação informa aos consumidores o que mudou entre as versões.
• Envie diffs pequenos. Uma mudança lógica por PR. PRs de especificação grandes escondem alterações que quebram a compatibilidade no ruído.
• Escreva mensagens de commit descritivas. “Adicionar refundReason à requisição de reembolso” é melhor do que “atualizar especificação.”
• Nunca edite a especificação mesclada diretamente na main. Sempre crie um branch, mesmo para um erro de digitação.

FAQ

Como detecto alterações que quebram a compatibilidade em uma especificação OpenAPI?

Execute uma ferramenta de diff de especificações no CI que compare o pull request com a versão na main. Ferramentas como oasdiff classificam cada alteração como quebra de compatibilidade, não quebra de compatibilidade ou não classificada, e podem falhar a build em uma alteração que quebra a compatibilidade. Isso captura campos removidos, novos parâmetros obrigatórios e tipos alterados que uma revisão manual pode perder.

Devo manter um único arquivo OpenAPI ou dividi-lo em vários?

Comece com um único openapi.yaml. É o mais fácil de revisar e versionar. Quando o arquivo ficar grande ou você mantiver várias versões principais em paralelo, divida por versão principal (api-v1.yaml, api-v2.yaml) ou use $ref para dividir os schemas em arquivos separados. Não divida prematuramente; um arquivo legível é melhor do que cinco fragmentados.

Posso controlar a versão da minha especificação sem escrever YAML manualmente?

Sim. O Modo Spec-First do Apidog permite editar a especificação em um editor visual e sincronizar as alterações com o Git em ambas as direções. Ele escreve YAML consistente, então seus diffs permanecem limpos e seus pull requests legíveis, enquanto você ainda obtém histórico completo do Git e revisão.