Existem dois campos em toda equipe de API com a qual trabalhei.
Um escreve sua especificação OpenAPI à mão, a salva em um diretório specs/ e trata o Git como a fonte da verdade. O outro clica em um designer visual, exporta a especificação quando o CI reclama e corrige qualquer divergência que as duas representações tenham acumulado desde a última terça-feira.
Já estive em ambos os campos. O primeiro é mais lento no primeiro dia e mais rápido no nonagésimo dia. O segundo é o oposto. E até cerca de um mês atrás, a ferramenta de design de API que mais uso — Apidog — atendia apenas ao segundo campo. Seu designer visual é excelente. Seu round-trip YAML era um recurso que você tinha que defender na revisão de código.
Então, em meados de abril, o Modo Spec-First (Beta) apareceu na caixa de diálogo Novo Projeto. Eu deliberatei não escrever sobre isso no dia do lançamento. Queria usá-lo em algo real primeiro, e queria esperar tempo suficiente para que os bugs da primeira semana tivessem a chance de aparecer. Um mês é aproximadamente a quantidade de tempo certa. Esta postagem é o que encontrei depois de passar uma manhã com a versão beta, usando uma especificação OpenAPI de um dos meus projetos paralelos — o que eu diria a um colega de equipe antes de ele tentar, e onde ele se encaixa ou não.
O que o Modo Spec-First realmente muda
A versão curta: Apidog agora tem dois modos de projeto, e eles são produtos genuinamente diferentes por baixo.
O modo padrão é o que a maioria das pessoas conhece. Você clica em + Novo Projeto, obtém uma árvore de pastas e formulários visuais, e constrói endpoints preenchendo campos. A especificação OpenAPI é gerada por baixo dos panos. Funciona, especialmente para equipes que ainda não têm um forte hábito de YAML.
O Modo Spec-First substitui o editor de formulários por um editor de código real para arquivos .yaml e .json brutos, além de uma sincronização bidirecional com seu repositório Git. Sua especificação OpenAPI é o arquivo no disco, não uma serialização de cliques. Há destaque de sintaxe, autocompletar contra o esquema OpenAPI e um painel de "Análise de Diretório em Tempo Real" que constrói um esboço de endpoint na barra lateral a partir do seu código enquanto você digita.
Esse último detalhe é o que eu destacaria se estivesse demonstrando isso para um cético. A razão pela qual designers visuais existem não é porque YAML é difícil — é porque YAML esconde a estrutura até que você já tenha rolado por ela. A visualização de esboço do Apidog resolve isso sem fazer você abandonar o arquivo. Você escreve a especificação, obtém a navegação. Os dois coexistem na tela.
A tese, se é que existe uma: o desenvolvimento spec-first nunca foi sobre preferir editores de texto. Era sobre quem possui o artefato. O Modo Spec-First faz do artefato o arquivo em seu repositório, ponto final. A UI é uma janela para ele, não um invólucro em torno dele.
A configuração, de ponta a ponta
Aqui está o caminho que percorri. Demorou menos de dez minutos, a maior parte dos quais foi autorização Git.
1. Crie o projeto no modo certo. Na tela de projetos, + Novo Projeto → Geral → Modo Spec-first. O seletor de modo é fácil de perder se você tem criado projetos no piloto automático por um ano — o Modo Geral é sinalizado como "Recomendado" e seu olho passa direto pelo segundo bloco. Vá com calma aqui.
2. Conecte-se ao seu repositório Git. Role até Conectar com Repositório Git e autorize seu provedor. Usei o GitHub; a documentação cobre os outros. Em seguida, escolha a Organização, Repositório e Ramificação principal. Apidog sincronizará os arquivos de especificação nessa ramificação como sua cópia de trabalho.
3. Configure o projeto. Digite um Nome do Projeto, defina as permissões da equipe e Crie. A primeira sincronização puxa quaisquer arquivos .yaml e .json que vivem no repositório para o espaço de trabalho do Apidog.
4. Edite a especificação como um arquivo, não como um formulário. Abra um dos arquivos YAML. Você obtém um editor real, autocompletar sensível ao esquema, e o esboço de endpoint materializando-se na barra lateral enquanto você digita. Se você já passou algum tempo no VS Code com a extensão OpenAPI, isso parecerá familiar — exceto que o esboço está conectado à navegação, e clicar em um endpoint pula para a linha correta.
5. Faça commit e push. No canto superior direito, Commit & Push. A caixa de diálogo se abre para uma seção de Changes listando arquivos modificados, um campo de Commit Message e dois botões: Push ou Discard all changes. Não há uma etapa de preparação separada — qualquer coisa em Changes vai para o commit. Essa é uma simplificação deliberada, e para a maioria dos fluxos de trabalho de edição de especificação é a escolha certa.
6. Observe o indicador de sincronização. Canto inferior esquerdo — você pode vê-lo como Sincronizado agora na Figura 1. Ele informa se suas edições locais foram enviadas, puxadas ou estão fora de sincronia com o remoto. Deixei isso aberto em um canto da minha tela e se tornou a coisa em que confiei mais do que as caixas de diálogo modais. Se o indicador estiver verde, você e o repositório concordam.
Essa é a área de superfície completa. Seis passos, nenhum motor de sincronização separado para configurar, nenhum plugin para instalar.
O que notei que a documentação não diz
Três coisas que valem a pena mencionar, todas de uma manhã de experimentação.
A visualização do contorno atualiza mais rápido do que eu esperava. Já usei vários "editores OpenAPI ao vivo" no passado e a maioria deles reanalisa ao salvar, o que significa um atraso de 30 segundos entre adicionar um endpoint e vê-lo na barra lateral. O contorno do Apidog atualizou enquanto eu digitava — rápido o suficiente para que eu parasse de verificar. Isso parece uma coisa pequena. Não é. É a diferença entre confiar no contorno como auxílio de navegação e verificá-lo como um relatório de status.
A integração com o Git é genuinamente bidirecional. Editei o mesmo arquivo em meu clone local e fiz push do terminal enquanto o Apidog estava aberto. O Apidog percebeu, o indicador de sincronização mudou para "atrasado", e um clique puxou as alterações para o editor sem caixa de diálogo de mesclagem. A sincronização bidirecional que a documentação promete é a experiência real, não um resumo de marketing. Se você tem um colega de equipe que se recusa a usar qualquer coisa além do Vim, ele pode continuar usando o Vim, e você pode continuar usando o Apidog, e o arquivo no repositório permanece a única coisa que ambos estão editando.
Não há uma porta de saída para o designer visual no mesmo projeto. Isso é intencional, mas vale a pena saber antes de se comprometer. Se você escolher o Modo Spec-First na criação, esse projeto é spec-first. Você não pode mudar um projeto no meio do caminho porque os modelos de dados subjacentes são diferentes. Para uma equipe que deseja ambos os modos na mesma especificação, o fluxo de trabalho é: mantenha a especificação em um repositório, aponte um projeto Spec-First para ela e deixe os usuários do modo visual abrirem um projeto separado que importa da mesma fonte. Não é perfeito, mas é viável.
Onde ele se encaixa e onde não
Vou usar isso em produção. Essa é a resposta mais direta que posso dar. A combinação de um editor real, autocompletar que respeita o esquema OpenAPI e um indicador de sincronização em que posso confiar é o que eu queria do Apidog há dois anos.
Mas aqui está a versão honesta para quem isso é.
Ele se encaixa se você já escreve OpenAPI manualmente, ou deseja fazê-lo. Ele se encaixa se seu CI executa spectral lint ou gera SDKs de cliente a partir da especificação e a especificação precisa estar no Git de qualquer maneira. Ele se encaixa se você tem um engenheiro na equipe que de outra forma estaria abrindo pull requests contra o arquivo YAML do VS Code, e você quer que todos convergem para uma ferramenta sem forçá-los a abandonar seu teclado. E ele se encaixa especialmente bem se você tem gerenciado a divergência entre "a especificação no Apidog" e "a especificação no repositório" com uma etapa de make export em que ninguém confia.
Não se encaixa se sua equipe nunca tocou em OpenAPI e o designer visual é a razão pela qual eles podem contribuir. Para essas equipes, o modo padrão ainda é a escolha certa. O Modo Spec-First troca a facilidade de integração pela fidelidade, e essa troca está errada quando a maioria dos seus colaboradores não são especialistas em API.
Também não se encaixa, ainda, para equipes que precisam misturar ambos os modos no mesmo projeto. A versão beta é genuinamente uma beta nesse aspecto. Eu esperaria que isso se suavizasse nas próximas versões.
A conclusão
O desenvolvimento "spec-first" costumava significar optar por não usar ferramentas de design de API. Você vivia em YAML e abria mão dos test runners e mock servers, ou vivia em um designer visual e abria mão do Git como fonte da verdade. O movimento interessante no Modo Spec-First é que o Apidog parou de pedir para você escolher.
O arquivo em seu repositório é o arquivo no editor. O contorno é uma visualização, não um estado. A sincronização Git é o fio, não um recurso. Se você está esperando por uma plataforma de API que leve o "spec-first" a sério, em vez de tratá-lo como uma opção de exportação, este é o que eu experimentaria.
A versão beta está disponível na caixa de diálogo Novo Projeto hoje. Baixe o Apidog, escolha o Modo Spec-First na criação e aponte-o para um repositório em que você já confia. O primeiro commit leva dez minutos. A decisão sobre mantê-lo leva cerca de uma semana.