Como Sincronizar Especificação OpenAPI com GitHub: 2 Métodos

Se o seu documento OpenAPI está em um repositório Git, mas você o edita dentro de um cliente de API, o atrito é previsível: copiar YAML, colar de volta, verificar se ninguém alterou o arquivo e torcer para que a importação não tenha descartado nada. Este guia mostra como sincronizar sua especificação OpenAPI com GitHub usando o Modo Spec-First do Apidog, mantendo repositório e editor alinhados como uma única fonte da verdade.

Experimente o Apidog hoje

Você vai conectar um provedor Git, abrir um projeto diretamente de um repositório, editar o YAML OpenAPI e enviar a alteração de volta para o GitHub. O mesmo fluxo também funciona com GitLab.

O que a sincronização bidirecional realmente significa

Sincronização bidirecional significa que as alterações fluem nos dois sentidos, sem exportação manual.

• Apidog → Git: você edita o documento OpenAPI no Apidog, faz commit e envia a alteração para a branch escolhida.
• Git → Apidog: quando alguém altera a mesma branch pelo IDE ou pelo repositório, o Apidog puxa a versão atualizada para o editor.

Na prática, o repositório continua sendo a fonte da verdade. O Apidog funciona como um editor rico sobre o Git. Essa é a base de um fluxo de trabalho de API nativo do Git: a especificação é versionada, revisada e rastreada como qualquer outro arquivo do projeto.

Pré-requisitos

Antes de começar, confirme que você tem:

• Apidog instalado ou acesso à versão web, com login feito.
• Um repositório GitHub ou GitLab com um documento OpenAPI existente, ou um repositório no qual você tenha permissão de escrita.
• Modo Spec-First, atualmente em beta, ativado.
• Permissão de escrita na branch que será sincronizada.

O Azure DevOps também é suportado via Git Connection.

Passo 1: Conecte seu provedor Git

Autorize o Apidog a acessar o provedor onde está seu repositório.

1. Abra o Apidog.
2. Crie um novo projeto.
3. Escolha Modo Spec-First.
4. Na seleção de fonte, escolha GitHub ou GitLab.
5. Clique em Autorizar.
6. No navegador, conceda acesso aos repositórios necessários.

No GitHub, você pode limitar o acesso a repositórios específicos em vez de autorizar a conta inteira.

Depois da autorização, você volta para o Apidog com o provedor conectado. Essa configuração precisa ser feita apenas uma vez por provedor; projetos futuros podem reutilizar a conexão.

Para detalhes do fluxo, incluindo Azure DevOps via Git Connection, consulte a documentação do Modo Spec-First.

Passo 2: Crie um projeto a partir do repositório

Agora aponte o Apidog para o arquivo OpenAPI real.

1. Selecione o repositório que contém a especificação.
2. Escolha a branch que será sincronizada, por exemplo main.
3. Informe ou confirme o caminho do documento OpenAPI, se solicitado:
   • openapi.yaml
   • openapi.yml
   • docs/openapi.yaml
   • outro caminho usado no seu repositório
4. Crie o projeto.

O Apidog carrega a especificação dessa branch e analisa o documento. Endpoints e schemas aparecem na barra lateral, permitindo navegar pela API enquanto o YAML continua sendo o arquivo versionado no Git.

Passo 3: Edite o YAML OpenAPI

No Modo Spec-First, você edita o OpenAPI diretamente em um editor estilo IDE, com:

• realce de sintaxe;
• validação em linha;
• autocompletar;
• atualização da árvore de endpoints e schemas enquanto você digita.

Exemplo: adicionando um endpoint simples de health check.

paths:
  /health:
    get:
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

Enquanto você edita:

• a operação /health aparece na navegação lateral;
• problemas de indentação são sinalizados;
• campos obrigatórios ausentes são indicados;
• referências inválidas, como $ref quebrado, podem ser detectadas antes do commit.

Isso reduz a chance de descobrir erros apenas no pipeline ou na geração de documentação.

Se você quiser aprofundar o uso de diffs e histórico em especificações OpenAPI, veja o guia sobre controle de versão OpenAPI com Git.

Passo 4: Faça commit e push

Quando a alteração estiver pronta, envie-a para o GitHub.

1. Abra o painel de Git ou controle de código-fonte no projeto.
2. Revise o diff da especificação.
3. Escreva uma mensagem de commit clara, por exemplo:

Add /health endpoint

1. Clique em Commit & Push.

O Apidog cria o commit na branch configurada e envia para o remoto. Ao abrir o repositório no GitHub, você verá o commit no histórico da branch, modificando o arquivo OpenAPI.

Se você mudar de ideia antes do envio, descarte as edições não enviadas. Nada chega ao repositório remoto até você executar Commit & Push.

Passo 5: Verifique o status da sincronização

Use o indicador de sincronização para confirmar o estado do projeto.

Após um push bem-sucedido, o Apidog mostra um estado como:

Sincronizado agora mesmo

Isso indica que o editor e a branch remota contêm a mesma versão do documento.

Com o tempo, o indicador pode mostrar algo como:

Sincronizado há 5 minutos

Se outra pessoa fizer push na mesma branch, o Apidog puxa a alteração e atualiza o estado após a reconciliação.

Se o indicador mostrar um estado pendente ou desatualizado, trate isso como sinal de divergência entre sua cópia local e o remoto. Antes de continuar, puxe as alterações ou resolva conflitos.

Solução de problemas

Push falha por permissão

Possíveis causas:

• token expirado;
• autorização revogada;
• acesso removido ao repositório;
• branch protegida.

Ações recomendadas:

1. Refaça a autorização do provedor Git.
2. Verifique se você tem permissão de escrita.
3. Confirme se a branch aceita commits diretos.

Commit foi para a branch errada

Confirme a branch selecionada durante a criação do projeto. Se a branch main for protegida e exigir pull requests, use uma branch de recurso, por exemplo:

feature/openapi-health-endpoint

Depois, abra um pull request normalmente no GitHub ou GitLab.

Conflito de merge

Se outra pessoa alterou o mesmo trecho do arquivo enquanto você editava, o remoto pode avançar em relação à sua cópia local.

Como resolver:

1. Puxe a versão mais recente.
2. Compare os trechos conflitantes no YAML.
3. Mantenha a versão correta ou combine as mudanças.
4. Valide o documento.
5. Faça commit novamente.

Como OpenAPI é texto puro, a resolução segue o mesmo padrão de qualquer conflito Git.

Validação acusa erro no YAML

O Apidog pode sinalizar problemas como:

• indentação incorreta;
• bloco responses ausente;
• schema malformado;
• $ref inválido;
• tipos incompatíveis.

Corrija esses pontos antes de enviar. Uma especificação válida mantém documentação, mocks e testes mais confiáveis.

FAQ

A sincronização com GitHub também funciona com GitLab e Azure DevOps?

Sim. O Modo Spec-First suporta GitHub e GitLab diretamente. Azure DevOps é suportado via Git Connection. O fluxo geral é o mesmo: conectar o provedor, abrir o repositório, editar, fazer commit e enviar.

O que acontece se alguém editar a especificação no repositório enquanto eu trabalho no Apidog?

O Apidog puxa a alteração como parte da sincronização bidirecional. Se as mudanças estiverem em partes diferentes do arquivo, elas tendem a ser mescladas normalmente. Se houver sobreposição, você resolve um conflito Git padrão.

Posso desfazer uma alteração antes que ela chegue ao GitHub?

Sim. Antes de clicar em Commit & Push, suas alterações continuam locais. Use a opção de descartar edições não enviadas para voltar ao último estado sincronizado.