Colaboração nativa Git para Testes e Engenharia de API

Sua especificação OpenAPI é o contrato entre sua API e seus consumidores. Mas onde esse contrato reside?

Com muita frequência, as especificações de API ficam em ferramentas isoladas — exportadas uma vez, esquecidas e raramente atualizadas quando a implementação muda. A documentação se desalinha. As coleções de testes divergem. Os revisores aprovam as alterações de código sem nunca ver as atualizações correspondentes da especificação.

O Modo Spec-first inverte esse modelo. Seus arquivos OpenAPI ou Swagger se tornam a fonte da verdade, armazenados diretamente em seu repositório Git junto com o código de implementação. Cada alteração na especificação flui pelos mesmos branches, pull requests e processo de revisão que você já usa. O design de API, o teste e a documentação ficam todos sincronizados — automaticamente.

Neste tutorial, vou guiá-lo pela configuração de um projeto Spec-first no Apidog, editando especificações com sua equipe e mantendo tudo em sincronia com seu fluxo de trabalho Git.

O que é o Modo Spec-first?

Em um projeto de API típico, você cria endpoints através de formulários visuais ou importa especificações existentes como ponto de partida. A ferramenta armazena as definições da API internamente, e a integração com o Git (se disponível) é uma etapa de exportação.

O Modo Spec-first é diferente. O espaço de trabalho primário é baseado em arquivos:

• openapi.yaml ou openapi.json residem em seu repositório
• O Apidog analisa esses arquivos e gera uma estrutura de API navegável
• Você edita os arquivos diretamente (ou através de formulários suportados)
• As alterações sincronizam automaticamente de volta para o Git

O arquivo de especificação é sempre autoritário. O Apidog lê dele, escreve nele e o mantém sincronizado com seu repositório.

Pré-requisitos

Para acompanhar, você precisará de:

• Uma conta Apidog (o plano gratuito funciona)
• Um repositório Git com um arquivo OpenAPI/Swagger, ou um repositório vazio para começar do zero
• Acesso de escrita ao repositório
• Familiaridade básica com a sintaxe OpenAPI ou Swagger

Etapa 1: Criar um Projeto Spec-first

Clique em + Novo Projeto no Apidog e escolha Modo Spec-first como o tipo de projeto.

Em seguida, conecte seu provedor Git:

1. Selecione seu provedor (GitHub, GitLab, Azure DevOps ou Bitbucket)
2. Escolha uma organização ou espaço de trabalho
3. Selecione um repositório existente ou crie um novo
4. Selecione o branch principal para sincronização

O Apidog sincronizará com o branch padrão do seu repositório. Se não for nomeado main, o Apidog se adapta automaticamente.

Etapa 2: Configurar Sincronização por Webhook (Recomendado)

Durante a configuração, você verá uma opção para instalar um webhook. Isso permite a sincronização automática sempre que sua equipe enviar alterações para o repositório.

Nota: A instalação do webhook geralmente requer permissão de administrador no repositório. Se você não tiver acesso de administrador, pule esta etapa — você ainda pode sincronizar manualmente usando Git Pull.

Benefícios do webhook:

• A equipe envia alterações → O Apidog sincroniza automaticamente
• Não é necessário atualização manual
• Todos veem o estado mais recente da especificação

Se você pulou a configuração do webhook inicialmente, pode adicioná-lo mais tarde em Configurações do Projeto > Git & Branches.

Etapa 3: Explorar o Espaço de Trabalho de Especificações

Após a criação, seu projeto abre o espaço de trabalho Specs — o hub central para edição baseada em arquivos e operações Git.

Três painéis trabalham juntos:

Clique em um endpoint na árvore de estrutura → O Apidog destaca a seção correspondente em seu arquivo-fonte. Navegue da visão de API de alto nível para o YAML de baixo nível sem trocar de abas.

Etapa 4: Editar Seus Arquivos de Especificação

Visualização de Código: Edição Direta

Para a maioria dos arquivos — YAML, JSON, Markdown — use a visualização de Código para editar o texto bruto.

Suas edições permanecem no arquivo. O Apidog não as transforma nem as armazena separadamente. O arquivo de especificação permanece a única fonte da verdade.

Visualização de Formulário: Edição Estruturada

Para nós OpenAPI suportados — endpoints, esquemas, definições e visão geral da API — mude para a visualização de Formulário.

A visualização de formulário é útil quando:

• Adicionar endpoints com todos os campos obrigatórios sem memorizar a estrutura YAML
• Editar esquemas visualmente
• Atualizar definições de segurança e metadados da API

Se um nó não suportar edição em formulário, o Apidog o manterá na visualização de código.

Etapa 5: Validar e Pré-visualizar Instantaneamente

O Modo Spec-first inclui validação em tempo real e pré-visualização da documentação — sem a necessidade de ferramentas externas.

Verificar Problemas com a Validação

Clique em Validação no cabeçalho do editor. Um painel mostra todos os avisos e erros em sua especificação atual.

O distintivo exibe a contagem total de problemas. Identifique:

• Erros de sintaxe
• Campos obrigatórios ausentes
• Violações de esquema
• Problemas de convenção de nomenclatura

Corrija os problemas antes de fazer o commit. Os revisores da sua equipe não precisarão identificá-los manualmente.

Pré-visualizar Sua Documentação

Clique em Pré-visualizar para ver como sua especificação é renderizada como documentação de API.

Para endpoints, a pré-visualização inclui duas abas:

Para esquemas e definições, a pré-visualização mostra a visualização da documentação renderizada.

Validação e Pré-visualização compartilham o mesmo painel lateral. Abrir um fecha automaticamente o outro.

Etapa 6: Puxar Atualizações da Sua Equipe

Quando colaboradores enviam alterações para seu repositório, traga-as para o Apidog:

1. Abra o espaço de trabalho Specs
2. Clique no nome do branch atual na barra lateral
3. Selecione Git Pull

Se a sincronização por webhook estiver ativa, o Apidog puxa automaticamente os eventos de push do repositório — sem a necessidade de etapas manuais.

Etapa 7: Fazer Commit e Push das Suas Alterações

Após editar arquivos no Apidog, envie suas atualizações de volta para o Git:

1. Faça alterações no espaço de trabalho Specs
2. Clique em Alterações na barra lateral para ver arquivos modificados, adicionados, renomeados e excluídos
3. Clique em Commit & Push
4. Selecione quais arquivos incluir
5. Escreva uma mensagem de commit
6. Clique em Push

Suas atualizações de especificação agora aparecem no mesmo fluxo de trabalho de pull request que suas alterações de código. Colegas de equipe podem revisar, comentar e aprovar — tanto a implementação quanto o contrato da API em um só lugar.

Dica: Use Descartar todas as alterações se quiser abandonar as edições locais antes de fazer o push.

Etapa 8: Trabalhar com Branches

O Modo Spec-first suporta colaboração baseada em branches completa. O Apidog mapeia branches Git para branches de projeto, permitindo que você alterne entre versões de especificação.

Operações Comuns de Branch

O gerenciamento de branches funciona da mesma forma que você espera do Git — branches de funcionalidades, releases e desenvolvimento paralelo sincronizam corretamente.

Etapa 9: Integrar com CI/CD

Como suas especificações residem no Git, elas se encaixam naturalmente em pipelines de automação:

• Verificar especificações em cada PR usando validação do Apidog ou ferramentas como Spectral
• Gerar documentação automaticamente quando as especificações são mescladas no `main`
• Executar testes de API acionados por alterações na especificação
• Sincronizar com sistemas downstream — gateways de API, servidores mock, geradores de SDK

Exemplo de fluxo de trabalho do GitHub Actions:

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

Suas especificações de API agora passam pelos mesmos portões de qualidade que o código da sua aplicação.

Alternativa: Projetos Baseados em Armazenamento

Se você não está pronto para conectar um repositório Git externo, o Apidog oferece projetos Spec-first baseados em armazenamento.

Esses projetos usam o armazenamento interno do Apidog, mas ainda fornecem:

• Edição baseada em arquivos
• Validação e pré-visualização
• Gerenciamento de branches

Os rótulos da interface do usuário se ajustam ligeiramente:

• Git Pull torna-se Sincronizar
• Commit & Push torna-se Salvar

Migre para o Git externo quando sua equipe estiver pronta.

Resumo

Com o Modo Spec-first, seu fluxo de trabalho de API se torna:

O Modo Spec-first torna os arquivos OpenAPI o contrato que deveriam ser — versionados, revisados e sempre alinhados com seu código.

Pronto para experimentar? Crie um projeto Spec-first no Apidog e conecte seu primeiro repositório.