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

Se o seu documento OpenAPI reside em um repositório Git, mas você o edita dentro de um cliente de API, você já conhece o atrito: copie o YAML, cole-o de volta, espere que ninguém mais tenha tocado no arquivo e reze para que a importação não tenha silenciosamente descartado um campo. Manter uma especificação e um repositório em acordo manualmente é o tipo de tarefa que falha exatamente quando você está com pressa.

Este guia mostra como sincronizar sua especificação OpenAPI com o GitHub usando o Modo Spec-First do Apidog, para que a especificação em seu repositório e a especificação em seu editor permaneçam a mesma coisa, em vez de duas cópias que você constantemente precisa reconciliar. Conectaremos um provedor, abriremos um projeto diretamente de um repositório, editaremos o YAML e enviaremos a alteração de volta para o GitHub em uma única passagem. Os mesmos passos funcionam para o GitLab.

Vamos começar.

O que a sincronização bidirecional realmente significa

Sincronização bidirecional significa que as edições fluem em ambas as direções, automaticamente, sem uma etapa de exportação no meio.

• Apidog para Git: Quando você edita o documento OpenAPI no Apidog e faz um commit, a alteração é enviada para o seu repositório como um commit Git normal na branch que você escolheu.
• Git para Apidog: Quando um colega de equipe (ou você, do seu IDE) envia uma alteração para essa branch, o Apidog a puxa de volta para que seu editor reflita o que realmente está no repositório.

O repositório é a única fonte da verdade. O Apidog é um editor rico construído sobre ele. Essa é a ideia principal por trás de um fluxo de trabalho de API nativo do Git: a especificação é versionada, revisada e tem seu histórico rastreado como qualquer outro arquivo em sua base de código, em vez de ficar em uma ferramenta que periodicamente exporta um snapshot.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Apidog instalado (aplicativo de desktop ou web), com login feito.
• Um repositório GitHub ou GitLab que já contenha um documento OpenAPI, ou um ao qual você tenha acesso de escrita. O Azure DevOps também é suportado através do Git Connection.
• Modo Spec-First (beta) ativado. Este é o modo que transforma seu projeto em uma camada fina sobre um repositório Git, em vez do próprio armazenamento do Apidog.

Você precisará de permissão de escrita na branch que planeja sincronizar. O acesso somente leitura permite puxar, mas não enviar.

Passo 1: Conecte seu provedor Git

Primeiro, autorize o Apidog a se comunicar com seu provedor.

1. Abra o Apidog e crie um novo projeto, escolhendo o Modo Spec-First.
2. Quando solicitado a escolher uma fonte, selecione seu provedor, GitHub ou GitLab.
3. Clique em Autorizar. Seu navegador abrirá a tela OAuth do provedor.
4. Conceda ao Apidog acesso aos repositórios que você deseja sincronizar. No GitHub, você pode restringir isso a repositórios específicos, em vez de toda a sua conta.

Assim que a autorização for concluída, você será redirecionado ao Apidog com o provedor conectado. Você faz isso apenas uma vez por provedor, futuros projetos reutilizam a conexão.

Para a referência completa sobre este fluxo, incluindo Azure DevOps via Git Connection, consulte a documentação do Modo Spec-First.

Passo 2: Crie um projeto a partir de um repositório e branch

Agora, aponte o Apidog para a especificação real.

1. Com o provedor conectado, escolha o repositório que contém seu arquivo OpenAPI.
2. Escolha a branch para sincronizar, geralmente main. Esta é a branch em que seus commits cairão e a branch que o Apidog observa para alterações de entrada.
3. Confirme o caminho para o documento OpenAPI se o Apidog perguntar (por exemplo, openapi.yaml na raiz do repositório, ou em docs/).
4. Crie o projeto.

O Apidog clona a especificação dessa branch e a abre. A barra lateral esquerda é preenchida com seus endpoints e schemas, porque o Apidog analisou o documento em um esquema navegável. Você está agora olhando a especificação do repositório, ao vivo.

Passo 3: Edite seu YAML OpenAPI no editor de código

O Modo Spec-First oferece um editor estilo IDE para o YAML OpenAPI bruto, com realce de sintaxe, validação em linha e autocompletar. Você escreve OpenAPI diretamente; o Apidog mantém o esquema visual atualizado enquanto você digita.

Vamos adicionar um pequeno endpoint. Suponha que você queira uma verificação de saúde:

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ê digita, duas coisas acontecem. A barra lateral esquerda analisa automaticamente o esquema, então sua nova operação /health aparece na árvore imediatamente. E o validador sinaliza problemas em linha, um bloco responses ausente, um $ref inválido, um erro de indentação, antes mesmo de você fazer o commit. Se o YAML estiver malformado, você o verá sublinhado em vez de descobri-lo em um pipeline falho mais tarde.

É aqui também que o controle de versão mostra seu valor. Se você quiser uma visão mais aprofundada de como as diferenças (diffs) e o histórico se manifestam em uma especificação, o guia sobre controle de versão OpenAPI com Git aborda isso.

Passo 4: Commit e push

Quando a edição estiver correta, envie-a para o GitHub.

1. Abra o painel de commit (a área de Git/controle de código-fonte do projeto).
2. Revise a alteração. O Apidog mostra o que foi modificado em relação à versão sincronizada.
3. Escreva uma mensagem de commit, trate-a como qualquer commit: Add /health endpoint.
4. Clique em Commit & Push.

O Apidog faz o commit na branch escolhida e envia para o repositório remoto. Abra seu repositório no GitHub e você verá o commit no histórico da branch, com a autoria esperada, tocando exatamente o arquivo OpenAPI.

Mudou de ideia antes de enviar? Você pode descartar edições não enviadas para reverter o documento ao último estado sincronizado. Nada sai do Apidog até você fazer o commit, então experimentos locais permanecem locais.

Passo 5: Verifique o status da sincronização

O Apidog mostra um indicador de sincronização para que você sempre saiba sua situação.

Após um push bem-sucedido, o indicador mostra "Sincronizado agora mesmo". Essa é a sua confirmação de que o editor e a branch remota contêm o mesmo documento. Com o tempo, ele se atualiza ("Sincronizado há 5 minutos") e, quando outra pessoa faz um push, o Apidog puxa a alteração e redefine o indicador após a reconciliação.

Se o indicador mostrar um estado pendente ou desatualizado, ele está informando que a cópia local e o remoto divergiram, sua deixa para puxar ou resolver antes de continuar.

Solução de problemas

Algumas coisas tendem a confundir as pessoas pela primeira vez.

• Autorização expirada ou revogada. Se os pushes começarem a falhar com um erro de permissão, execute novamente a autorização do Passo 1. Os tokens podem ser revogados pelo provedor ou simplesmente expirar.
• Branch errada. Enviar para uma branch main protegida que exige pull requests será rejeitado. Sincronize com uma branch de recurso ou ajuste as regras de proteção da branch. Verifique novamente se a branch escolhida no Passo 2 corresponde ao local onde você espera que os commits caiam.
• Conflitos de merge. Se um colega de equipe enviou para a mesma branch enquanto você estava editando, o remoto avançou em relação à sua cópia local. Puxe a versão mais recente, reconcilie o YAML sobreposto e faça o commit novamente. Como a especificação é texto puro, os conflitos são resolvidos da mesma forma que qualquer conflito de código.
• Erros de validação bloqueiam seu fluxo. O Apidog não o impedirá de fazer commit de YAML inválido, mas você deve corrigir o que o validador em linha sinaliza primeiro. Uma especificação limpa mantém seus documentos gerados, mocks e testes honestos.

FAQ

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

Sim. O Modo Spec-First suporta GitHub e GitLab diretamente, e Azure DevOps através do Git Connection. O fluxo de conectar-editar-commit-enviar é o mesmo para os três; apenas a tela de autorização difere por provedor.

O que acontece se um colega de equipe editar a especificação no repositório enquanto eu estou trabalhando no Apidog?

O Apidog puxa a alteração deles de volta para o seu editor como parte da sincronização bidirecional. Se suas edições e as deles tocam em partes diferentes do arquivo, elas se mesclam limpas. Se houver sobreposição, você resolverá um conflito Git padrão, exatamente como faria em qualquer arquivo de texto.

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

Sim. Até você clicar em Commit & Push, suas edições são locais. Use "descartar edições não enviadas" para reverter o documento ao último estado sincronizado, e nada chegará ao remoto.