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

Sua especificação OpenAPI é um contrato. Quando ela se desvia do comportamento real da API, clientes quebram, mocks ficam obsoletos e testes validam uma API que não existe mais. Trate a especificação como código: coloque-a no Git, crie branches, revise diffs e valide cada alteração antes de fazer merge.

Experimente o Apidog hoje

Este guia mostra um fluxo prático para versionar OpenAPI com Git: onde manter o arquivo, como organizar branches, o que revisar em pull requests, como validar no CI e como enviar alterações diretamente pelo Apidog.

Por que versionar sua especificação OpenAPI

Uma especificação em uma wiki ou drive compartilhado não oferece rastreabilidade suficiente. Você não consegue responder facilmente:

• Quem alterou o payload de POST /orders?
• Quando um campo passou a ser obrigatório?
• Qual commit introduziu uma alteração incompatível?
• Como voltar para a versão anterior do contrato?

Ao colocar openapi.yaml no Git, você ganha:

• Histórico: cada alteração tem autor, data e mensagem de commit.
• Blame: git blame openapi.yaml mostra quem adicionou ou alterou cada trecho.
• Rollback: um merge ruim pode ser revertido.
• Revisão: mudanças no contrato passam por pull requests antes de entrar na main.

Essa é 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 manter o arquivo OpenAPI no repositório

Mantenha uma estrutura simples e previsível. Para a maioria dos serviços, use um único arquivo openapi.yaml na raiz ou em uma pasta api/:

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

Se você mantém várias versões principais em paralelo, separe por versão:

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

Use essa abordagem quando v1 precisa permanecer estável para clientes existentes enquanto v2 evolui. Isso reduz ruído nos diffs e deixa claro qual contrato está sendo alterado.

Essa organização segue a ideia de API spec as code: a especificação deve ser versionada, revisada e validada como qualquer outro artefato do projeto.

Dica prática: documente a convenção no README.md. O pior cenário é ter dois arquivos diferentes alegando ser “a especificação oficial”.

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

Você não precisa de um modelo de branching exclusivo para OpenAPI. Use o mesmo fluxo do código:

1. Crie um branch a partir da main.
2. Altere a especificação.
3. Rode validações locais ou no CI.
4. Abra um pull request.
5. Faça merge após revisão.

Uma convenção simples ajuda revisores e automações a identificarem mudanças de contrato:

Tipo de alteração	Padrão	Exemplo
Novo endpoint	api/add-<recurso>	api/add-estornos
Alteração de campo	api/change-<recurso>-<campo>	api/change-status-pedido
Alteração incompatível	api/breaking-<descricao>	api/breaking-v2-autenticacao
Correção ou limpeza	api/fix-<descricao>	api/fix-schema-paginacao

Exemplos:

git checkout main
git pull
git checkout -b api/add-estornos

O prefixo api/ deixa claro que o PR afeta o contrato. Para mudanças incompatíveis, breaking- sinaliza que a alteração precisa de revisão extra e provavelmente de incremento de versão principal.

Mantenha branches pequenos e de curta duração. Um branch de especificação aberto por semanas tende a conflitar com alterações de outros times.

Como revisar alterações OpenAPI em um pull request

Um PR de especificação é uma alteração de contrato. Revise como você revisaria uma mudança de código que pode quebrar consumidores.

Escreva YAML de forma amigável para diffs:

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"

Boas práticas para facilitar revisão:

• Use indentação consistente.
• Mantenha uma propriedade por linha.
• Evite reordenar grandes blocos sem necessidade.
• Não misture refatoração de formatação com mudança de contrato.
• Faça uma alteração lógica por PR.

Checklist de revisão

Ao revisar um diff de OpenAPI, verifique:

• Mudanças incompatíveis

  • Algum campo obrigatório foi adicionado a uma requisição?
  • Algum campo de resposta foi removido ou renomeado?
  • Algum enum perdeu valores?
  • Algum tipo mudou, por exemplo de string para integer?

• Compatibilidade retroativa

  • Novos endpoints geralmente são seguros.
  • Novos campos opcionais geralmente são seguros.
  • Mudanças em formatos existentes exigem cuidado.

• Consistência

  • O nome do endpoint segue o padrão da API?
  • A pluralização está consistente?
  • Os códigos de status seguem o restante do serviço?

• Completeza

  • Toda operação tem summary?
  • As respostas de sucesso e erro estão documentadas?
  • Os schemas estão referenciados corretamente?

• Exemplos

  • Existem exemplos realistas de request e response?
  • Os exemplos ajudam mocks, documentação e testes?

Não dependa apenas de revisão manual para detectar alterações incompatíveis. Use uma etapa de CI para comparar a especificação do PR com a versão da main.

Commit e push pelo Apidog

Editar YAML manualmente funciona, mas um editor visual com validação em tempo real reduz erros e acelera o trabalho. O Modo Spec-First do Apidog permite sincronização Git bidirecional: você edita endpoints, schemas e exemplos na UI, faz commit e envia para o repositório sem sair da ferramenta.

Fluxo recomendado:

1. Conecte o repositório Git ao Apidog.
2. Aponte o Apidog para o arquivo OpenAPI, por exemplo api/openapi.yaml.
3. Edite endpoints, schemas e exemplos no editor visual.
4. Revise as alterações geradas.
5. Faça commit em um branch.
6. Envie o branch e abra o PR no seu fluxo normal.

Como o Apidog serializa o YAML de forma consistente, os diffs tendem a permanecer menores e mais legíveis, sem reordenações ou reformatações desnecessárias.

Veja a configuração completa na documentação do Modo Spec-First do Apidog. Se você usa GitHub, consulte também como fazer a sincronização da sua especificação OpenAPI com o GitHub.

Validação no CI

Nunca permita que uma especificação inválida chegue à main. Adicione validações ao pipeline de pull request para bloquear contratos quebrados automaticamente.

Um exemplo mínimo com GitHub Actions e Redocly CLI:

name: Validate OpenAPI

on:
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI spec
        run: npx @redocly/cli lint api/openapi.yaml

Esse job valida estrutura, estilo e problemas comuns na especificação.

Você pode evoluir o pipeline com mais verificações:

• Fazer lint da especificação.
• Validar se o arquivo é OpenAPI 3.x válido.
• Comparar o PR com a main.
• Bloquear alterações incompatíveis.
• Gerar documentação ou mocks apenas após validação.

Exemplo conceitual para detectar breaking changes com uma ferramenta de diff:

oasdiff breaking main:api/openapi.yaml HEAD:api/openapi.yaml

A ideia é simples: se o PR remove campos, adiciona parâmetros obrigatórios ou altera tipos de forma incompatível, o CI deve falhar antes do merge.

Melhores práticas para versionar OpenAPI

Adote hábitos simples para manter a especificação saudável:

• Use versionamento semântico

  • Atualize info.version.
  • Mudanças incompatíveis indicam nova versão principal.
  • Adições retrocompatíveis indicam versão secundária.

• Mantenha um changelog

  • Use um CHANGELOG.md próximo da especificação.
  • Registre alterações relevantes para consumidores da API.

• Prefira PRs pequenos

  • Uma mudança lógica por PR.
  • Diffs menores são mais fáceis de revisar.

• Escreva commits descritivos

  • Bom: Adicionar refundReason à requisição de reembolso
  • Ruim: Atualizar spec

• Nunca edite direto na main

  • Mesmo correções pequenas devem passar por branch e PR.

• Evite reformatação desnecessária

  • Reformatação em massa esconde mudanças de contrato.
  • Se precisar reformatar, faça isso em um PR separado.

FAQ

Como detectar alterações incompatíveis em uma especificação OpenAPI?

Execute uma ferramenta de diff no CI comparando a especificação do PR com a versão da main. Ferramentas como oasdiff conseguem classificar alterações como incompatíveis, compatíveis ou não classificadas.

Isso ajuda a capturar problemas como:

• Campos removidos.
• Novos parâmetros obrigatórios.
• Tipos alterados.
• Valores de enum removidos.
• Mudanças em formatos de resposta.

Devo manter um único arquivo OpenAPI ou dividir em vários?

Comece com um único openapi.yaml. É mais fácil de revisar, versionar e validar.

Divida apenas quando houver necessidade real, por exemplo:

• O arquivo ficou grande demais.
• Você mantém várias versões principais em paralelo.
• Schemas compartilhados precisam ser reutilizados.
• O time já tem maturidade para lidar com múltiplos arquivos e $ref.

Uma estrutura possível:

api/
├── openapi.yaml
└── components/
    ├── schemas/
    │   └── order.yaml
    └── responses/
        └── errors.yaml

Não divida cedo demais. Um arquivo único e legível costuma ser melhor do que vários fragmentos difíceis de rastrear.

Posso versionar 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.

Você ainda mantém:

• Histórico completo no Git.
• Branches e pull requests.
• Revisão de diffs.
• Validação no CI.
• Controle sobre o arquivo OpenAPI final.