Sua especificação OpenAPI é o contrato entre sua API e seus consumidores. Para manter esse contrato confiável, ele precisa viver no mesmo lugar que o código: no Git.
Quando a especificação fica isolada em uma ferramenta, ela tende a ficar desatualizada: a implementação muda, a documentação não acompanha, as coleções de teste divergem e os revisores aprovam PRs sem validar o contrato da API.
O Modo Spec-first muda esse fluxo. Seus arquivos OpenAPI ou Swagger passam a ser a fonte da verdade, versionados no repositório Git junto com a implementação. Assim, design de API, testes e documentação permanecem sincronizados com branches, commits e pull requests.
Neste tutorial, você vai configurar um projeto Spec-first no Apidog, editar arquivos de especificação e sincronizar as mudanças com seu fluxo Git.
O que é o Modo Spec-first?
Em um projeto de API tradicional, você geralmente cria endpoints em formulários visuais ou importa uma especificação inicial. A ferramenta armazena as definições internamente, e o Git entra apenas como uma etapa de exportação.
No Modo Spec-first, o fluxo é baseado em arquivos:
-
openapi.yamlouopenapi.jsonficam no seu repositório - O Apidog lê esses arquivos e gera uma estrutura navegável da API
- Você edita os arquivos diretamente ou por formulários suportados
- As alterações são sincronizadas de volta para o Git
Ou seja: o arquivo de especificação continua sendo a fonte autoritativa. O Apidog lê, valida, edita e sincroniza esse arquivo.
Pré-requisitos
Antes de começar, você precisa de:
- Uma conta Apidog
- Um repositório Git com um arquivo OpenAPI/Swagger ou um repositório vazio
- Permissão de escrita no repositório
- Conhecimento básico de OpenAPI ou Swagger
Exemplo mínimo de arquivo openapi.yaml para iniciar um repositório vazio:
openapi: 3.0.3
info:
title: Minha API
version: 1.0.0
paths:
/health:
get:
summary: Verifica o status da API
responses:
'200':
description: API disponível
Etapa 1: Criar um projeto Spec-first
No Apidog:
- Clique em + Novo Projeto
- Escolha Modo Spec-first
- Conecte seu provedor Git
- Selecione o repositório
- Escolha o branch principal para sincronização
Provedores suportados incluem:
- GitHub
- GitLab
- Azure DevOps
- Bitbucket
O Apidog sincroniza com o branch padrão do repositório. Se ele não se chamar main, o Apidog detecta e usa o branch configurado no repositório.
Etapa 2: Configurar sincronização por webhook
Durante a configuração, o Apidog pode solicitar a instalação de um webhook. Use essa opção sempre que possível.
O webhook permite que o Apidog sincronize automaticamente quando alguém envia alterações para o repositório.
Nota: instalar o webhook geralmente exige permissão de administrador no repositório. Se você não tiver essa permissão, pule a etapa e use Git Pull manualmente.
Com webhook ativado:
- Um desenvolvedor faz push para o repositório
- O Apidog detecta o evento
- A especificação é atualizada no projeto
- A equipe vê a versão mais recente
Se você pular essa configuração, poderá adicioná-la depois em:
Configurações do Projeto > Git & Branches
Etapa 3: Navegar pelo workspace de especificações
Depois de criar o projeto, abra o workspace Specs.
Ele é dividido em três áreas principais:
| Painel | O que mostra |
|---|---|
| Explorador de Arquivos | Arquivos e pastas do repositório sincronizado |
| Árvore de Estrutura da API | Endpoints, esquemas, definições e visão geral extraídos do OpenAPI |
| Editor | Edição em código ou formulário |
Fluxo prático:
- Clique em um endpoint na árvore da API
- O Apidog localiza a seção correspondente no arquivo OpenAPI
- Edite o YAML/JSON ou use a visualização em formulário quando disponível
Isso ajuda a navegar entre a visão de alto nível da API e o arquivo-fonte sem alternar entre ferramentas.
Etapa 4: Editar arquivos de especificação
Edição em código
Use a visualização de Código para editar diretamente arquivos YAML, JSON ou Markdown.
Exemplo de alteração em um endpoint:
paths:
/users/{id}:
get:
summary: Buscar usuário por ID
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Usuário encontrado
'404':
description: Usuário não encontrado
As alterações continuam no arquivo. O Apidog não cria uma cópia separada da definição da API.
Edição em formulário
Para nós OpenAPI suportados, como endpoints, esquemas, definições e visão geral da API, você pode usar a visualização de Formulário.
Use o formulário para:
- Criar endpoints sem memorizar toda a estrutura YAML
- Editar parâmetros, responses e schemas visualmente
- Atualizar metadados da API
- Configurar definições de segurança
Se um nó não suportar edição em formulário, o Apidog mantém a edição em código.
Etapa 5: Validar e pré-visualizar a especificação
O Modo Spec-first inclui validação em tempo real e pré-visualização da documentação.
Validar problemas
Clique em Validação no cabeçalho do editor.
O painel mostra avisos e erros encontrados na especificação, como:
- Erros de sintaxe YAML/JSON
- Campos obrigatórios ausentes
- Violações de schema
- Problemas de nomenclatura
- Definições incompletas
Corrija esses problemas antes do commit. Isso reduz retrabalho durante a revisão do PR.
Pré-visualizar documentação
Clique em Pré-visualizar para verificar como a especificação será renderizada como documentação.
Para endpoints, a pré-visualização inclui:
| Aba | Conteúdo |
|---|---|
| Documentação | Documentação gerada do endpoint |
| Experimentar | Painel de requisição ao vivo baseado na definição do endpoint |
Para schemas e definições, a pré-visualização mostra a documentação renderizada.
Validação e Pré-visualização usam o mesmo painel lateral. Abrir um fecha o outro.
Etapa 6: Puxar alterações da equipe
Quando outra pessoa altera a especificação no Git, atualize seu workspace:
- Abra Specs
- Clique no nome do branch atual
- Selecione Git Pull
Se o webhook estiver ativo, o Apidog sincroniza automaticamente após eventos de push no repositório.
Use Git Pull manualmente quando:
- O webhook não estiver configurado
- Você quiser garantir que está vendo a versão mais recente
- Houve alterações recentes em outro branch
Etapa 7: Fazer commit e push das suas alterações
Depois de editar a especificação no Apidog:
- Abra Alterações na barra lateral
- Revise arquivos modificados, adicionados, renomeados ou excluídos
- Clique em Commit & Push
- Selecione os arquivos que farão parte do commit
- Escreva uma mensagem clara
- Clique em Push
Exemplos de mensagens de commit úteis:
docs: adiciona endpoint GET /users/{id}
fix: corrige schema de resposta de criação de usuário
feat: adiciona autenticação bearer na especificação
Depois do push, as alterações entram no mesmo fluxo de pull request usado pelo código. A equipe pode revisar implementação e contrato da API no mesmo processo.
Dica: use Descartar todas as alterações se quiser abandonar edições locais antes do push.
Etapa 8: Trabalhar com branches
O Modo Spec-first suporta colaboração baseada em branches. Branches Git são mapeados para branches do projeto no Apidog.
Operações comuns:
| Ação | Como fazer |
|---|---|
| Alternar branches | Clique no nome do branch e selecione outro |
| Importar branch Git existente | Clique em Importar Novo Branch, selecione e importe |
| Criar novo branch | Vá em Configurações do Projeto > Git & Branches > Novo Branch |
| Corrigir problemas de sincronização | Use Re-sincronizar nas configurações do branch |
| Visualizar logs de sincronização | Acesse Ações do Branch > Visualizar Logs |
Fluxo recomendado para uma alteração de API:
- Crie um branch de feature
- Atualize
openapi.yaml - Valide a especificação
- Faça commit e push
- Abra um pull request
- Revise contrato e implementação juntos
Exemplo:
git checkout -b feat/users-search
No Apidog, importe ou selecione esse branch e edite a especificação correspondente.
Etapa 9: Integrar com CI/CD
Como a especificação está no Git, ela pode passar pelos mesmos gates de qualidade do código.
Você pode usar o pipeline para:
- Validar OpenAPI em cada PR
- Executar lint com ferramentas como Spectral
- Gerar documentação quando alterações forem mescladas no
main - Acionar testes de API a partir de mudanças na especificação
- Sincronizar com gateways, mocks ou geradores de SDK
Exemplo de workflow com 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
Com isso, uma alteração inválida no contrato da API pode ser bloqueada antes do merge.
Alternativa: projetos baseados em armazenamento
Se você ainda não quer conectar um repositório Git externo, o Apidog também oferece projetos Spec-first baseados em armazenamento.
Eles usam o armazenamento interno do Apidog, mas ainda oferecem:
- Edição baseada em arquivos
- Validação
- Pré-visualização
- Gerenciamento de branches
A interface muda levemente:
- Git Pull vira Sincronizar
- Commit & Push vira Salvar
Use essa opção para começar rapidamente e migre para Git externo quando o time estiver pronto.
Resumo
Com o Modo Spec-first, o fluxo de trabalho da API fica mais próximo do fluxo de desenvolvimento:
| Antes do Spec-first | Depois do Spec-first |
|---|---|
| Especificações ficam em uma ferramenta separada | Especificações ficam no repositório Git |
| Sincronização via export/import | Sincronização automática ou via Git Pull |
| Revisões fora do fluxo de código | Revisões em pull requests |
| Documentação gerada separadamente | Pré-visualização durante a edição |
| Testes desconectados da especificação | Testes acionados por mudanças no contrato |
O Modo Spec-first mantém arquivos OpenAPI versionados, revisáveis e alinhados com a implementação.
Para começar, crie um projeto Spec-first no Apidog, conecte seu repositório e trate sua especificação como parte do código.
Top comments (0)