Como integrar Apidog com GitHub e GitLab

Se suas especificações de API residem no Apidog, mas sua fonte de verdade está no Git, você quer que as duas estejam em sincronia. A integração Git do Apidog preenche essa lacuna. Ela permite que você conecte um repositório GitHub, GitLab ou Azure DevOps ao seu projeto, envie suas especificações OpenAPI para controle de versão e puxe as alterações do repositório de volta para o Apidog. Você obtém um registro de auditoria limpo, revisão de código nas alterações de especificação e um backup que sobrevive a qualquer coisa que aconteça dentro do aplicativo.

Esta é a referência ampla. Ela cobre todos os provedores que o Apidog suporta, ambas as maneiras como o produto se comunica com o Git, e as decisões práticas que você enfrentará: qual repositório, qual branch, quem pode enviar e o que fazer quando algo quebra. Se você precisa apenas do guia focado no GitHub, leia o guia dedicado sobre como sincronizar sua especificação OpenAPI com o GitHub. Aqui, abordamos um escopo mais amplo.

O que a integração Git do Apidog faz

O Apidog se comunica com o Git de duas maneiras distintas. Elas resolvem problemas diferentes, e você pode usar uma, a outra ou ambas. Misturá-las é a fonte mais comum de confusão, então vamos separá-las primeiro.

A primeira capacidade é a sincronização bidirecional através do Modo Spec-First. Você edita seu documento OpenAPI como YAML ou JSON dentro do editor estilo IDE do Apidog, confirma suas alterações e as envia para o branch conectado. Quando outra pessoa atualiza a especificação no repositório, você puxa essas alterações de volta para o Apidog. Este é um verdadeiro ciclo completo: as edições fluem para o Git e as alterações do repositório fluem de volta.

A segunda capacidade é o backup automático Git de especificações de API. Aqui, o Apidog exporta o arquivo OpenAPI/Swagger de cada módulo e o envia para um repositório em um cronograma. Isso é unidirecional e sem intervenção. Você configura uma vez, e o sistema mantém uma cópia versionada de suas especificações no Git sem que você precise mover um dedo. É uma rede de segurança, não um fluxo de trabalho de edição.

Mantenha essa distinção em mente para o restante do artigo. Quando dizemos “sincronizar”, queremos dizer o fluxo bidirecional do Modo Spec-First. Quando dizemos “backup”, queremos dizer a exportação agendada e unidirecional.

Provedores Git suportados

O Apidog suporta os três provedores que a maioria das equipes já usa. GitHub e GitLab se conectam diretamente através de seus fluxos de autorização nativos. O Azure DevOps se conecta através de uma Conexão Git genérica, que funciona com qualquer host Git que utilize autenticação HTTPS padrão.

A Conexão Git genérica é a solução de escape. Se seu host não é GitHub ou GitLab por nome, mas se comunica via Git padrão sobre HTTPS com autenticação por token, a conexão genérica geralmente o suporta. O Azure DevOps é o caso principal, mas o mesmo caminho cobre configurações self-hosted que expõem uma URL de clone HTTPS.

Conectando seu provedor Git

A etapa de conexão é onde você concede ao Apidog o acesso necessário para ler e escrever em seu repositório. A mecânica difere ligeiramente por provedor, mas a forma é a mesma: autorizar, escolher um repositório, escolher um branch.

Para o GitHub, você autoriza através da tela OAuth do GitHub. O Apidog solicita acesso ao repositório para que possa ler a especificação e enviar commits. Se o repositório pertencer a uma organização, o GitHub pode rotear a solicitação através de um administrador da organização que aprova o acesso de terceiros. Repositórios pessoais autorizam imediatamente sob sua própria conta.

Para o GitLab, o fluxo espelha o GitHub. Você faz login através da tela OAuth do GitLab e concede acesso ao repositório. O GitLab self-managed funciona desde que o Apidog consiga alcançar a instância pela rede.

Para o Azure DevOps, você usa a Conexão Git genérica. Em vez de um handshake OAuth, você fornece a URL de clone HTTPS do repositório e um token de acesso pessoal (PAT). Crie o PAT no Azure DevOps com permissão para ler e escrever código, depois cole-o no Apidog. O token é a credencial que permite ao Apidog enviar commits, então defina seu escopo para exatamente os repositórios que ele precisa.

Algumas notas de permissão que economizam tempo:

• Repositórios de organização vs. pessoais. Repositórios de organização frequentemente exigem que um administrador aprove a integração uma vez. Se sua autorização parece ter sucesso, mas o Apidog não consegue ver o repositório, geralmente falta uma aprovação do administrador.
• Defina o escopo do token rigidamente. Para Azure DevOps e qualquer conexão genérica, conceda ao PAT permissão de leitura/escrita no código apenas para o projeto de destino. Evite tokens de conta completa.
• Repositórios privados funcionam. O Apidog funciona com repositórios privados. O acesso vem da autorização ou token que você fornece, não da visibilidade pública.

Uma vez que o provedor é conectado, você cria o projeto Apidog a partir de um repositório mais um branch, tipicamente main. Essa combinação é o que vincula suas especificações a um local específico no controle de versão. Se você é novo na prática mais ampla, nosso guia sobre controle de versão OpenAPI com Git cobre as convenções que valem a pena adotar antes de conectar tudo.

Sincronização bidirecional com o Modo Spec-First

O Modo Spec-First é onde a sincronização bidirecional reside. Ele transforma o Apidog em um editor de especificações que faz commits para o Git como qualquer outro código. Você pode ler a referência completa na documentação oficial do Apidog; aqui está como o ciclo completo funciona na prática.

Você edita o documento OpenAPI diretamente como YAML ou JSON. O editor é estilo IDE: oferece destaque de sintaxe, validação em tempo real e autocompletar, então um `$ref` malformado ou um campo obrigatório ausente aparece enquanto você digita, e não depois de você fazer o push. Enquanto você edita, a barra lateral esquerda analisa automaticamente o documento em um contorno, caminhos, operações e esquemas, para que você possa navegar em uma especificação grande sem rolar o texto bruto.

Uma edição típica se parece com isso. Digamos que você adicione um endpoint:

paths:
 /v1/orders/{orderId}:
 get:
 operationId: getOrder
 summary: Retrieve a single order
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: The requested order
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/Order'

Quando você salva essa alteração, o Apidog a prepara como uma edição local. Você então faz um commit com uma mensagem e envia para o branch conectado, exatamente como faria com qualquer fluxo de trabalho Git. Após o push ser concluído, um indicador de sincronização exibirá “Sincronizado agora mesmo” confirmando que o Apidog e o branch contêm o mesmo conteúdo.

A direção do pull é igualmente importante. Quando um colega de equipe edita a especificação no repositório e faz um push, você puxa essas alterações para o Apidog para manter sua cópia local atualizada. É isso que torna a integração genuinamente bidirecional: o repositório não é apenas um alvo de backup, é um par.

Se você fizer edições que não deseja manter, pode descartar edições não enviadas antes de confirmar. Isso reverte sua cópia de trabalho para corresponder ao último estado sincronizado, o que é útil quando você está experimentando e decide que a alteração não vale a pena ser mantida.

Esse ritmo de commit e push é o coração de um fluxo de trabalho de API nativo do Git — as alterações de especificação passam pelo mesmo processo de revisão, histórico e reversão que o resto do seu código. Os revisores comentam o diff YAML em um pull request, as aprovações controlam a fusão, e seu histórico de design de API é como seu histórico de código.

Backup automático Git de especificações de API

A capacidade de backup é a parte mais silenciosa da integração Apidog Git, e ela quase não exige nada de você após a configuração. Você aponta um módulo para um repositório, e o Apidog cuida do resto.

Aqui está o mecanismo. O Apidog pode fazer backup do arquivo OpenAPI/Swagger para cada módulo em um repositório Git; GitHub, GitLab e Azure DevOps são todos suportados. Depois de salvar a configuração de backup, o sistema envia automaticamente o arquivo de Especificação OpenAPI do módulo para o repositório especificado. O push acontece durante uma janela aleatória fora do horário de pico à noite, o que o mantém fora do seu horário de trabalho e distribui a carga.

O que é armazenado é o documento OpenAPI/Swagger exportado para aquele módulo, um instantâneo do contrato da API tal como está. Como cada push é um commit, você acumula um histórico de versões no Git. Você pode comparar o contrato da semana passada com o de hoje, ver exatamente quando um campo mudou e restaurar uma versão anterior diretamente do repositório, se for necessário.

O fluxo de backup é unidirecional por design. O Apidog escreve no repositório; ele não lê alterações de volta. Se você quer que as edições do repositório fluam para o Apidog, essa é a função do Modo Spec-First, não do backup. Use o backup quando seu objetivo é durabilidade e histórico sem alterar como sua equipe trabalha no dia a dia.

Escolhendo um branch e estrutura de repositório

As decisões estruturais que você toma de antemão moldam o quão suave a integração será depois. Duas perguntas dominam: qual branch e quantos repositórios.

Escolha do branch. A maioria das equipes sincroniza para main para a especificação canônica e usa branches para o design em andamento. Apontar o Apidog para um branch permite que você itere em uma alteração de especificação isoladamente, abra um pull request e faça o merge assim que a revisão for aprovada; seu design de API segue o mesmo modelo de ramificação que seu código. Apontar o Apidog diretamente para main é mais simples, mas pula o portão de revisão, então reserve-o para pequenas equipes ou mudanças de baixo risco.

Um repositório ou muitos. Não há uma única resposta certa, mas as compensações são claras:

• Um repositório por API mantém o histórico de cada especificação limpo e seus controles de acesso restritos. É o ajuste natural quando equipes diferentes são proprietárias de APIs diferentes.
• Um monorepo para todas as especificações centraliza tudo e simplifica a pesquisa e revisão entre APIs. Funciona bem quando uma equipe de plataforma é proprietária da superfície da API. Apenas mantenha o layout do diretório previsível, uma pasta por módulo, para que backups e sincronizações não entrem em conflito.

Se você usa um monorepo, dê a cada módulo seu próprio caminho. Isso mantém os backups automáticos organizados e facilita a leitura das diferenças de especificação na revisão.

Permissões de equipe e acesso

A integração Git envolve credenciais, por isso vale a pena ser deliberado sobre quem pode fazer o quê. As permissões residem em dois lugares: dentro do Apidog e dentro do seu provedor Git.

Dentro do Apidog, as permissões da equipe são configuradas durante a configuração do projeto. É lá que você decide quem pode sincronizar e enviar para o repositório conectado. Limite os direitos de push às pessoas que possuem a especificação e permita que todos os outros leiam. Isso evita pushes acidentais de contribuidores que estão apenas navegando pelo design da API.

Dentro do seu provedor Git, a credencial importa. Para GitHub e GitLab, a autorização OAuth carrega o acesso do usuário que a concedeu. Para Azure DevOps e conexões genéricas, o token de acesso pessoal é a credencial, trate-o como um segredo. Não cole tokens em documentos compartilhados, defina o escopo para os repositórios de destino apenas e gire-os na mesma cadência em que você gira outros segredos. Se alguém sair da equipe, revogue seu token e reautorize sob uma conta que ainda esteja ativa.

O princípio é simples: a integração é tão segura quanto o token mais fraco por trás dela. Mantenha os escopos restritos e a propriedade clara.

Lidando com conflitos de merge e desvio

Como o Apidog faz commits de histórico Git real, ele herda o modelo de conflito do Git e as ferramentas do Git para resolvê-lo. Conflitos acontecem quando duas pessoas alteram a mesma parte da especificação antes de sincronizar.

Imagine o cenário. Você edita o esquema `Order` no Apidog e faz push. Um colega de equipe editou o mesmo esquema no lado do repositório e fez push primeiro. Quando você tenta reconciliar, o Git sinaliza um conflito no YAML, porque ambos os lados alteraram linhas sobrepostas. Este não é um problema do Apidog; é um conflito de merge Git normal em um arquivo YAML, e você o resolve da maneira normal.

Para evitar conflitos, puxe antes de enviar. Trazer o estado mais recente do repositório para o Apidog antes de confirmar suas próprias alterações mantém sua cópia de trabalho atualizada e diminui a janela onde duas edições colidem. Quando um conflito ocorre, resolva-o no YAML da mesma forma que você resolveria qualquer conflito de merge: escolha as linhas corretas, mantenha o documento válido e sincronize novamente. A validação em tempo real do editor ajuda aqui; um merge mal feito que quebra a estrutura OpenAPI aparece imediatamente, em vez de depois que você faz o push.

O desvio, onde Apidog e o repositório divergem silenciosamente, é a versão lenta do mesmo problema. O indicador “Sincronizado agora mesmo” é seu aviso precoce. Se ele não mostrar “sincronizado”, algo está não enviado ou não puxado. Trate isso como um lembrete para reconciliar antes que a lacuna aumente.

Solução de problemas

A maioria dos problemas de integração remonta à autenticação, seleção de branch ou uma sincronização interrompida. Verifique a tabela antes de assumir que algo mais profundo está errado.

Se a autorização é o tema recorrente, e geralmente é, comece confirmando que a credencial está ativa e com o escopo correto. Um token revogado ou uma aprovação de organização ausente explica a maioria dos relatos de "simplesmente parou de funcionar".

FAQ

A sincronização é unidirecional ou bidirecional?

Depende da capacidade que você está usando. O Modo Spec-First é bidirecional: você envia edições para o Git e puxa as alterações do repositório de volta para o Apidog. O backup automático é unidirecional: o Apidog exporta a especificação de cada módulo para o repositório em um cronograma e não lê as alterações de volta.

Onde minhas especificações são armazenadas?

No repositório Git que você conecta. Para o Modo Spec-First, seu documento OpenAPI vive no branch para o qual você faz push. Para backup automático, o arquivo OpenAPI/Swagger exportado de cada módulo é commitado no repositório que você configurou. Em ambos os casos, o Git mantém a cópia versionada, e você mantém controle total do repositório.

Para qual branch devo sincronizar?

Use main para a especificação canônica e branches para as mudanças em andamento. Sincronizar com um branch permite que uma alteração de especificação passe por um pull request e revisão antes de ser mesclada, o que espelha como seu código já se move através do Git.

O que acontece se meu token for revogado?

Os pushes começam a falhar porque o Apidog não tem mais acesso de escrita. Reautorize o provedor ou, para Azure DevOps e conexões genéricas, gere um novo token de acesso pessoal e atualize-o no Apidog. Uma vez restaurada a credencial, a sincronização e o backup são retomados normalmente.

Conclusão

A integração Git do Apidog oferece duas ferramentas complementares: sincronização bidirecional através do Modo Spec-First para equipes que tratam a especificação como código, e backup automático por módulo para qualquer um que apenas queira uma rede de segurança versionada. Ambas funcionam com GitHub, GitLab e Azure DevOps, então você conecta o provedor que já usa em vez de adotar um novo.

Escolha a capacidade que corresponde ao seu objetivo. Se você quer revisão e histórico em cada alteração de especificação, configure o Modo Spec-First e adote o ritmo de commit e push. Se você quer durabilidade sem mudar seu fluxo de trabalho, ative o backup e deixe o push noturno cuidar disso. Muitas equipes usam ambos. Quando estiver pronto para conectar, conecte seu provedor, aponte um projeto para um repositório e branch, e deixe suas especificações de API viverem onde o resto do seu trabalho já reside.