DEV Community

Cover image for Passei Uma Manhã com o Modo Spec-First do Apidog: Designer Visual Não É Mais o Único Adulto na Sala
Lucas
Lucas

Posted on • Originally published at apidog.com

Passei Uma Manhã com o Modo Spec-First do Apidog: Designer Visual Não É Mais o Único Adulto na Sala

Existem dois perfis comuns em equipes de API: quem mantém a especificação OpenAPI no Git como fonte da verdade e quem desenha endpoints em uma interface visual, exportando a especificação quando o CI exige.

Experimente o Apidog hoje

Já trabalhei dos dois lados. Escrever OpenAPI à mão costuma ser mais lento no primeiro dia, mas mais previsível no longo prazo. Usar um designer visual acelera o início, mas pode criar divergência entre “a spec na ferramenta” e “a spec no repositório”.

Até recentemente, o Apidog atendia melhor ao segundo fluxo. O designer visual continua sendo o modo padrão. Mas, em abril, o Modo Spec-First Beta apareceu na criação de novos projetos.

Passei uma manhã usando esse modo com uma especificação OpenAPI real de um projeto paralelo. Este artigo resume como configurar, como editar, como sincronizar com Git e em quais cenários o modo faz sentido.

O que muda no Modo Spec-First

O Apidog agora tem dois modos de projeto:

  • Modo Geral: você cria endpoints por formulários visuais; a especificação OpenAPI é gerada por trás.
  • Modo Spec-First: você edita arquivos .yaml ou .json diretamente; esses arquivos vivem no seu repositório Git.

Na prática, o Modo Spec-First troca o editor visual por:

  • editor de código para OpenAPI;
  • suporte a YAML e JSON;
  • autocompletar baseado no schema OpenAPI;
  • análise em tempo real da estrutura da especificação;
  • navegação por endpoints na barra lateral;
  • sincronização bidirecional com Git.

A diferença importante é esta: a especificação não é uma exportação da UI. Ela é o arquivo no repositório.

O espaço de trabalho do Modo Spec-First, durante a edição de um projeto pet-store. A barra lateral esquerda é o esboço de caminho auto-gerado — observe Paths (224) no topo, depois rotas individuais como /store/auth/{email}, /admin/auth, /store/token materializando-se diretamente do arquivo. Canto superior direito: o indicador Changes (1) e o botão verde Commit & Push. Canto inferior esquerdo: Synced just now — o indicador de status de sincronização que a prosa faz referência mais tarde.

O painel lateral é útil porque YAML não mostra estrutura por si só. Em uma spec grande, navegar por paths, components, schemas e responses pode ser lento. O Apidog mantém o arquivo como fonte principal, mas cria uma visualização navegável a partir dele.

Exemplo simples de endpoint em OpenAPI:

openapi: 3.0.3
info:
  title: Store API
  version: 1.0.0

paths:
  /store/token:
    post:
      summary: Gera um token de acesso
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        "200":
          description: Token gerado com sucesso
Enter fullscreen mode Exit fullscreen mode

Ao editar algo assim, o endpoint aparece na árvore lateral sem você precisar exportar, importar ou atualizar manualmente.

Configuração passo a passo

O fluxo completo levou menos de dez minutos. A parte mais demorada foi autorizar o acesso ao GitHub.

1. Crie um projeto no modo correto

Na tela de projetos:

+ Novo Projeto → Geral → Modo Spec-first
Enter fullscreen mode Exit fullscreen mode

O detalhe importante: o Modo Geral aparece como recomendado. Se você cria projetos no automático, é fácil ignorar o bloco do Modo Spec-first.

2. Conecte o repositório Git

Na seção Conectar com Repositório Git, autorize seu provedor Git.

Depois selecione:

  • Organização
  • Repositório
  • Ramificação principal

Usei GitHub, mas o fluxo é o mesmo: o Apidog passa a sincronizar os arquivos de especificação dessa branch com o workspace.

3. Configure o projeto

Defina:

  • nome do projeto;
  • permissões da equipe;
  • repositório e branch;
  • modo Spec-First.

Depois clique em Criar.

Na primeira sincronização, o Apidog busca os arquivos .yaml e .json existentes no repositório.

Os passos 1-3 ocorrem na mesma caixa de diálogo. Acima: os dois blocos de modo. O Modo Geral é sinalizado como Recomendado, o que torna o bloco do Modo Spec-first (à direita, selo Beta, destaque roxo) o mais fácil de ignorar. O bloco Spec-first lista o que muda por baixo: Editor de Especificação OpenAPI (Suporta Visualização) e Sincronização bidirecional com o repositório Git. Abaixo: o painel Conectar com Repositório Git com menus suspensos para Organização, Repositório (pet-store) e Ramificação Principal (main), além do campo Nome do Projeto. Uma tela, três decisões.

4. Edite a spec como arquivo

Abra um arquivo YAML ou JSON.

Você verá:

  • editor de código;
  • autocompletar;
  • destaque de sintaxe;
  • árvore de endpoints;
  • navegação para a linha correspondente ao clicar em uma rota.

Se você já usa VS Code com extensão OpenAPI, a experiência é familiar. A diferença é que o Apidog combina editor, navegação e contexto de API no mesmo workspace.

Um fluxo típico fica assim:

1. Abrir openapi.yaml
2. Adicionar ou alterar um path
3. Conferir se o endpoint apareceu na barra lateral
4. Ajustar schemas, responses e requestBody
5. Fazer Commit & Push
Enter fullscreen mode Exit fullscreen mode

5. Faça commit e push pelo Apidog

No canto superior direito, clique em:

Commit & Push
Enter fullscreen mode Exit fullscreen mode

A janela mostra:

  • arquivos modificados;
  • campo de mensagem de commit;
  • ação de push;
  • opção para descartar alterações.

Não há uma etapa separada de staging. Tudo que estiver em Changes entra no commit.

Exemplo de mensagem de commit:

docs: add token endpoint to OpenAPI spec
Enter fullscreen mode Exit fullscreen mode

A caixa de diálogo Push to Git repo. Observe a estrutura: um campo de Mensagem de Commit, uma lista de Alterações (1 arquivo) com uma caixa de seleção por arquivo, e três botões na parte inferior — Descartar todas as alterações (esquerda, destrutivo), Cancelar (neutro) e Push (a ação primária, roxo). Ao fundo, você pode ver o botão Commit & Push no canto superior direito da área de trabalho que abriu esta caixa de diálogo.

6. Acompanhe o status de sincronização

No canto inferior esquerdo, o indicador mostra se o workspace está sincronizado com o repositório.

Use isso como verificação rápida:

Synced just now
Enter fullscreen mode Exit fullscreen mode

Se o status estiver sincronizado, o arquivo no editor e o arquivo remoto estão alinhados.

O que percebi usando em um projeto real

Alguns pontos ficaram mais claros durante o uso do que lendo a documentação.

A árvore de endpoints atualiza rápido

Em alguns editores OpenAPI, a estrutura só atualiza ao salvar. Aqui, a árvore lateral atualizou enquanto eu digitava.

Isso muda o uso da navegação. Em vez de tratar a árvore como um relatório atrasado, dá para usá-la como parte do fluxo de edição.

A sincronização Git é realmente bidirecional

Testei este cenário:

1. Abrir o projeto no Apidog
2. Editar o mesmo arquivo em um clone local
3. Fazer commit e push pelo terminal
4. Voltar ao Apidog
Enter fullscreen mode Exit fullscreen mode

O Apidog detectou que o remoto estava à frente. Depois de puxar as mudanças, o editor foi atualizado.

Isso é importante para equipes mistas. Um dev pode continuar usando Vim ou VS Code, enquanto outro usa o Apidog. O ponto comum continua sendo o arquivo versionado no Git.

O projeto não alterna entre modos

Esse ponto merece atenção antes de criar o projeto.

Se você cria um projeto como Spec-First, ele permanece Spec-First. Não dá para alternar o mesmo projeto para o designer visual depois.

Isso parece intencional, porque os modelos internos são diferentes. Mas impacta equipes que querem misturar os dois fluxos.

Uma alternativa possível é:

1. Manter a especificação no repositório Git
2. Criar um projeto Spec-First apontando para esse repositório
3. Para usuários do modo visual, usar outro projeto importando a mesma fonte
Enter fullscreen mode Exit fullscreen mode

Não é o fluxo ideal, mas funciona se a equipe precisa dos dois modelos.

Quando usar o Modo Spec-First

Use o Modo Spec-First se sua equipe já trata OpenAPI como artefato principal.

Ele se encaixa bem quando:

  • a spec OpenAPI já fica no Git;
  • o CI valida a spec com ferramentas como spectral lint;
  • SDKs ou documentação são gerados a partir da spec;
  • pull requests já alteram arquivos YAML ou JSON;
  • você quer reduzir divergência entre ferramenta visual e repositório;
  • a equipe prefere revisar mudanças de API via diff.

Exemplo de validação comum em CI:

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Ou um fluxo local simples:

git pull
spectral lint openapi.yaml
git add openapi.yaml
git commit -m "docs: update store endpoints"
git push
Enter fullscreen mode Exit fullscreen mode

Com o Modo Spec-First, o Apidog entra nesse fluxo sem transformar a spec em uma exportação paralela.

Quando não usar

O Modo Spec-First não é a melhor escolha se sua equipe ainda não escreve OpenAPI manualmente.

Se o designer visual é o que permite que pessoas menos familiarizadas com YAML contribuam, o Modo Geral continua fazendo mais sentido.

Também vale cautela se você precisa alternar entre visual e spec-first dentro do mesmo projeto. Na versão beta, isso ainda não é o foco do fluxo.

Conclusão

O Modo Spec-First muda o papel do Apidog no fluxo de API.

Antes, a escolha era mais rígida:

Editor YAML + Git como fonte da verdade
ou
Designer visual + exportação da spec
Enter fullscreen mode Exit fullscreen mode

Com o Modo Spec-First, o arquivo no repositório passa a ser o arquivo editado no Apidog. A árvore de endpoints é uma visualização. A sincronização Git é parte do fluxo, não uma etapa manual de exportação.

Se sua equipe já trabalha com OpenAPI no Git, vale testar em um repositório real. Crie um projeto em Modo Spec-First, conecte a branch principal e faça uma alteração pequena. O primeiro commit leva poucos minutos. A decisão de manter no fluxo da equipe deve ficar clara depois de alguns dias de uso.

Top comments (0)