O que é Apidog Modo Spec-First

O Modo Spec-First do Apidog é um espaço de trabalho beta para equipes que tratam especificações OpenAPI como código-fonte. Em vez de preencher formulários, você edita openapi.yaml ou openapi.json diretamente em um editor estilo IDE, valida a especificação e sincroniza as alterações em duas vias com um repositório Git conectado. A especificação passa a ser o projeto.

Experimente o Apidog hoje

Este guia mostra como usar o recurso na prática: quando escolher o Modo Spec-First, como configurá-lo, como editar e versionar a especificação, quais integrações Git estão disponíveis e quais limitações esperar da versão beta. Para entender a abordagem por trás disso, veja o artigo sobre fluxo de trabalho de API git-nativo.

O que é o Modo Spec-First do Apidog?

O Modo Spec-First é um modo de edição beta no Apidog em que o design da API vive como um documento OpenAPI bruto.

Na prática, você:

1. Abre a especificação como YAML ou JSON.
2. Edita o arquivo diretamente.
3. Valida a estrutura OpenAPI enquanto escreve.
4. Faz commit das alterações.
5. Envia para o repositório Git conectado.
6. Puxa atualizações feitas por outros membros da equipe.

Esse fluxo foi criado para equipes que já trabalham com Git como parte central do desenvolvimento: backend, plataforma, infraestrutura e empresas API-first que revisam contratos de API via pull requests.

A principal diferença é simples: em vez de esconder a especificação atrás de uma interface visual, o Modo Spec-First mostra o arquivo.

Modo Spec-First vs Modo Design-First

O Apidog oferece dois modos de trabalho:

• Modo Design-First: editor visual baseado em formulários.
• Modo Spec-First: editor de código para YAML/JSON OpenAPI.

Para uma comparação mais detalhada, leia a comparação entre spec-first e design-first.

Aspecto	Modo Design-First	Modo Spec-First Beta
Editor principal	Formulários visuais e painéis de UI	Editor de código YAML/JSON bruto
Fonte da verdade	Banco de dados do projeto Apidog	Arquivo de especificação no repositório Git
Sincronização Git	Baseada em exportação/importação	Sincronização nativa bidirecional
Melhor para	Equipes mistas e fluxos visuais	Equipes de engenharia Git-nativas
Curva de aprendizado	Mais guiada	Familiar para quem conhece OpenAPI

Nenhum modo é universalmente melhor. Use o que combina com o fluxo real da sua equipe.

Principais recursos

O Modo Spec-First combina editor OpenAPI, navegação estrutural, integração Git e controles de equipe.

Editor OpenAPI estilo IDE

O centro do fluxo é um editor de código para documentos OpenAPI em YAML ou JSON.

Ele inclui:

• Realce de sintaxe.
• Validação contra a especificação OpenAPI.
• Preenchimento automático para OpenAPI e Swagger.
• Edição direta do arquivo bruto.

Isso ajuda a evitar erros comuns, como campos obrigatórios ausentes, objetos malformados ou referências inválidas.

Exemplo de trecho editado diretamente no arquivo:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Esse tipo de edição é útil quando você já conhece OpenAPI e quer trabalhar com a especificação como trabalharia com qualquer outro arquivo do projeto.

Estrutura navegável gerada automaticamente

Arquivos OpenAPI crescem rápido. Uma API real pode ter centenas ou milhares de linhas.

Para facilitar a navegação, o Apidog analisa o documento e monta uma estrutura lateral com:

• Paths.
• Operações.
• Schemas.
• Componentes.

Você pode clicar em uma operação, como POST /orders, e ir direto para o ponto correspondente no arquivo. A estrutura é atualizada conforme o documento muda.

Isso reduz a necessidade de procurar manualmente por linha ou usar busca textual o tempo todo.

Sincronização Git bidirecional

O recurso central do Modo Spec-First é a sincronização em duas vias com Git.

Você pode:

• Puxar alterações do repositório para o editor.
• Editar a especificação no Apidog.
• Fazer commit.
• Enviar alterações de volta para o Git.

Provedores suportados:

Provedor	Como se conecta
GitHub	Integração direta
GitLab	Integração direta
Azure DevOps	Via Conexão Git genérica

Se você quer um fluxo específico com GitHub, veja o guia sobre como sincronizar uma especificação OpenAPI com o GitHub.

Commit, push e status de sincronização

O Modo Spec-First segue um fluxo Git familiar.

Depois de editar a especificação, você:

1. Revisa as alterações.
2. Escreve uma mensagem de commit.
3. Faz commit.
4. Envia para o repositório conectado.
5. Confere o status de sincronização.

O indicador de sincronização mostra quando a especificação local está alinhada com o repositório. Quando o status indica que está sincronizado, a versão no editor corresponde à versão remota.

Isso evita dúvidas como:

• “Essa alteração já foi enviada?”
• “Minha versão está atualizada?”
• “O repositório tem algo mais recente?”

Rastreamento de alterações

Antes do commit, o Apidog mostra o que foi alterado no arquivo.

As mudanças podem aparecer como:

• Modificadas.
• Adicionadas.
• Excluídas.

Esse passo funciona como uma revisão local antes de publicar a alteração no Git. Se uma edição experimental não deve ser mantida, você pode descartá-la antes de enviá-la.

Essa prática ajuda a manter o histórico do repositório mais limpo.

Projeto com escopo de repositório e branch

Um projeto Spec-First é criado a partir de:

• Um repositório Git específico.
• Uma branch específica, como main.

Isso significa que o projeto sempre aponta para um local real no Git. A especificação, o histórico e a branch permanecem alinhados.

Durante a configuração, você também define permissões de equipe para controlar quem pode acessar o projeto e realizar alterações.

Como configurar o Modo Spec-First

A configuração é linear. O passo a passo oficial também está disponível na documentação do Modo Spec-First.

1. Mude para o Modo Spec-First

No Apidog:

1. Abra o módulo de APIs.
2. Vá até o seletor de modo no canto inferior esquerdo.
3. Altere de Design-First para Spec-First.

2. Conecte seu provedor Git

Escolha o provedor usado pela sua equipe:

• GitHub.
• GitLab.
• Azure DevOps via Conexão Git genérica.

Para GitHub e GitLab, use a integração direta. Para Azure DevOps, configure a conexão informando as credenciais Git padrão.

3. Crie um projeto a partir do repositório

Selecione:

1. O repositório que contém a especificação.
2. A branch desejada, geralmente main.
3. O arquivo OpenAPI, como openapi.yaml ou openapi.json.

O projeto ficará vinculado a esse repositório e branch.

4. Configure permissões da equipe

Defina quem pode acessar o projeto e quais permissões cada pessoa terá.

Esse passo é importante para equipes que tratam o contrato da API como artefato crítico.

5. Edite a especificação

Abra o arquivo no editor estilo IDE.

Use:

• A barra lateral para navegar por paths e schemas.
• O preenchimento automático para inserir campos OpenAPI.
• A validação para detectar problemas durante a escrita.

6. Revise e faça commit

Antes de commitar:

1. Abra o painel de alterações.
2. Verifique os arquivos modificados.
3. Descarte alterações indesejadas.
4. Escreva uma mensagem de commit clara.

Exemplo:

Adicionar endpoint POST /invoices

7. Envie para o repositório

Depois do commit, faça push para a branch conectada.

8. Verifique o status de sincronização

Confirme se o indicador mostra que a especificação está sincronizada com o repositório.

Esse é o ciclo principal:

pull -> editar -> validar -> revisar -> commit -> push -> sincronizar

Exemplo de fluxo diário

Depois de configurar o projeto, um fluxo comum pode ser assim:

1. Você começa puxando as alterações mais recentes da branch conectada.
2. Abre a estrutura lateral e navega até a operação que precisa alterar.
3. Edita o YAML diretamente.
4. Usa a validação para detectar erros.
5. Revisa as alterações.
6. Faz commit.
7. Envia para o repositório.
8. Outro membro da equipe revisa a alteração em um pull request.

Exemplo de schema adicionado durante esse fluxo:

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

Esse fluxo mantém o contrato da API versionado, revisável e sincronizado com o restante do código.

Quem deve usar o Modo Spec-First?

Use o Modo Spec-First se sua equipe:

• Já trabalha diariamente com Git.
• Versiona contratos de API em pull requests.
• Prefere editar YAML ou JSON diretamente.
• Quer manter a especificação OpenAPI junto ao código.
• Tem engenheiros de backend ou plataforma como principais autores da API.

Prefira o Modo Design-First se sua equipe:

• Quer uma interface visual guiada.
• Tem pessoas não técnicas colaborando no design da API.
• Prefere formulários em vez de edição manual de YAML.
• Trabalha melhor com uma experiência mais visual.

Se ainda estiver em dúvida, veja a postagem de comparação.

Limitações e observações da versão beta

O Modo Spec-First ainda está em beta. Isso significa que recursos e comportamentos podem mudar conforme o Apidog evolui o produto com base em feedback.

Pontos importantes:

• GitHub e GitLab têm integração direta.
• Azure DevOps usa Conexão Git genérica.
• Outros hosts Git podem depender da conexão genérica.
• O fluxo deve ser testado antes em um repositório não crítico.
• A disciplina Git continua sendo responsabilidade da equipe.

Como a especificação sincroniza com um repositório real, trate alterações com o mesmo cuidado usado no código:

• Faça commits intencionais.
• Revise mudanças antes de enviar.
• Descarte experimentos que não devem ir para o histórico.
• Valide o arquivo antes de compartilhar.

A vantagem da fase beta é que feedbacks iniciais podem influenciar o desenvolvimento do recurso.

FAQ

O Modo Spec-First é gratuito?

O Modo Spec-First é um recurso beta dentro do Apidog. O acesso depende do seu plano e da disponibilidade do recurso para sua conta. A forma mais direta de verificar é abrir o módulo de APIs e tentar habilitar o modo.

Quais provedores Git são suportados?

GitHub e GitLab são suportados por integração direta. Azure DevOps funciona por meio de uma Conexão Git genérica com credenciais Git padrão.

Outros hosts Git também podem funcionar via conexão genérica, desde que o fluxo use Git padrão.

Posso voltar para o Modo Design-First?

Sim. O seletor de modo fica no canto inferior esquerdo do módulo de APIs. Você pode alternar entre Spec-First e Design-First conforme o projeto exigir.

Quais formatos posso editar?

Você pode editar documentos OpenAPI em YAML ou JSON bruto. O editor oferece realce de sintaxe, validação de esquema e preenchimento automático para OpenAPI e Swagger.

O que acontece com edições não enviadas?

Edições não enviadas permanecem locais até que você faça push. O Modo Spec-First rastreia alterações modificadas, adicionadas ou excluídas. Se uma mudança não deve ser publicada, descarte-a antes de enviar.

Conclusão

O Modo Spec-First do Apidog coloca a especificação OpenAPI e o Git no mesmo fluxo. Você edita YAML ou JSON diretamente, navega pela estrutura analisada automaticamente, valida enquanto escreve, faz commit e sincroniza com GitHub, GitLab ou Azure DevOps.

Ele é mais indicado para equipes Git-nativas que querem tratar a especificação como código-fonte. Para testar com segurança, conecte um repositório não crítico, faça uma pequena alteração, commit e push, e valide se o fluxo atende à sua equipe.

Quando estiver pronto, consulte a documentação do Modo Spec-First e conecte o Apidog ao seu repositório.