O Modo Spec-First do Apidog é um espaço de trabalho beta construído para equipes que tratam suas especificações OpenAPI como código-fonte. Você escreve a especificação diretamente como YAML ou JSON em um editor no estilo IDE, e depois a sincroniza nos dois sentidos com um repositório Git conectado. Nenhum editor baseado em formulário fica entre você e o arquivo. A especificação *é* o projeto. Se você sempre quis editar `openapi.yaml` em um editor de código de verdade e enviá-lo para o GitHub sem sair da sua ferramenta de API, este é o modo para você.
Este guia é a referência completa para o próprio recurso. Ele aborda todas as funcionalidades, o passo a passo completo da configuração, para quem é, as limitações a serem esperadas de uma versão beta e um FAQ prático. Para a ideia mais ampla por trás desta abordagem, veja nosso 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 onde o design da sua API vive como um documento OpenAPI bruto. Você abre o arquivo, edita YAML ou JSON, o valida, o commita e o envia para o Git. O Apidog mantém a especificação e o repositório sincronizados em ambas as direções. Puxe uma alteração de um colega de equipe e seu editor será atualizado. Envie sua edição e o repositório será atualizado.
Ele foi construído especificamente para um tipo de equipe: pessoas que já utilizam um fluxo de trabalho Git nativo. Engenheiros de backend, equipes de plataforma e empresas com foco em API que versionam seus contratos em pull requests se sentirão em casa. O arquivo de especificação torna-se a única fonte de verdade, e o Git lida com o histórico, revisão e ramificação da mesma forma que faz para o resto do seu código-base.
Isso é diferente de como a maioria das ferramentas de API funciona. A maioria das ferramentas oculta a especificação atrás de um formulário gráfico. O Modo Spec-First mostra o arquivo.
Modo Spec-First vs Modo Design-First em resumo
O Apidog oferece dois modos. O Modo Design-First é o editor visual baseado em formulários com o qual a maioria das equipes começa. O Modo Spec-First é a abordagem de editor de código que este guia cobre. Aqui está a versão resumida. Para uma análise completa das vantagens e desvantagens, leia nossa 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 | O arquivo de especificação no seu repositório Git |
| Sincronização Git | Baseado em exportação/importação | Sincronização nativa bidirecional |
| Melhor para | Designers visuais, equipes mistas | Equipes de engenharia Git-nativas |
| Curva de aprendizado | Suave, guiada | Familiar se você conhece OpenAPI |
Nenhum dos modos é “melhor”. Eles atendem a diferentes equipes. Você pode alternar entre eles, o que abordaremos abaixo.
Principais recursos
O Modo Spec-First é mais do que uma caixa de texto. Ele agrupa um editor, um navegador, integração Git e controles de equipe. Aqui estão todas as funcionalidades em detalhes.
O editor OpenAPI no estilo IDE
O centro do espaço de trabalho é um editor de código completo para o seu documento OpenAPI. Você edita o YAML ou JSON bruto diretamente. Ele se comporta como o editor que você já usa todos os dias.
Você obtém realce de sintaxe que colore chaves, valores e estrutura para que o arquivo permaneça legível em escala. Você obtém validação de esquema que sinaliza erros contra a especificação OpenAPI enquanto digita, para que um objeto de resposta malformado ou um campo obrigatório ausente apareça imediatamente. Você obtém preenchimento automático ajustado para OpenAPI e Swagger, que sugere palavras-chave válidas, nomes de campos e estrutura enquanto você escreve.
Esse preenchimento automático é mais importante quando você está aprofundado em um esquema e não consegue se lembrar se é `additionalProperties` ou `additionalItems`. O editor conhece a especificação, então ele ajuda você a permanecer correto.
pequena parte do que você editaria:
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'
Estrutura navegável analisada automaticamente
Um arquivo de especificação bruto fica longo rapidamente. Uma API real pode ter milhares de linhas. O Modo Spec-First resolve isso com uma barra lateral esquerda que analisa automaticamente o arquivo em uma estrutura visual.
Enquanto você digita, o Apidog lê o documento e constrói uma estrutura navegável: caminhos, operações, esquemas e componentes. Clique em qualquer nó na estrutura e o editor pulará para aquele local no arquivo. Você navega pelo significado, não pela rolagem. A estrutura é atualizada em tempo real conforme a especificação muda, então ela sempre reflete o que realmente está no arquivo.
Isso mantém um `openapi.yaml` grande gerenciável. Você pensa em termos de “a operação `POST /orders`”, não “linha 1.847”.
Sincronização Git bidirecional
Este é o cerne do modo. O Modo Spec-First se conecta ao seu repositório Git e sincroniza a especificação em ambas as direções.
GitHub e GitLab são suportados diretamente. O Azure DevOps funciona através de uma Conexão Git genérica, que permite apontar o Apidog para o repositório usando credenciais Git padrão. Uma vez conectado, puxar (pull) traz as alterações do repositório para o seu editor, e enviar (push) envia suas edições de volta para o repositório. A especificação permanece consistente entre todos na equipe porque o Git é a espinha dorsal compartilhada.
| Provedor | Como se conecta |
|---|---|
| GitHub | Integração direta |
| GitLab | Integração direta |
| Azure DevOps | Via Conexão Git genérica |
Se você deseja um passo a passo focado em um provedor, nosso guia de sincronização da especificação OpenAPI com o GitHub detalha esse fluxo exato.
Commit, push e o indicador de status de sincronização
Você não apenas salva e espera. O Modo Spec-First segue o modelo Git que você já conhece. Ao finalizar uma edição, você escreve uma mensagem de commit e faz o commit da alteração. Em seguida, você a envia para o repositório conectado.
Um indicador de status de sincronização mantém você informado o tempo todo. Ele mostra estados como “Sincronizado agora” quando sua especificação local corresponde ao repositório, e muda quando você tem trabalho não enviado. Você sempre sabe se a versão à sua frente é a versão que seus colegas de equipe veem. Sem adivinhações, sem especificações desatualizadas.
Rastreamento de alterações de arquivo
Antes de fazer o commit, o Modo Spec-First mostra exatamente o que mudou. Ele rastreia as modificações no nível do arquivo e marca cada entrada como modificada, adicionada ou excluída. Você revisa o conjunto de alterações da mesma forma que revisaria uma saída de status do Git.
Isso é importante porque oferece um ponto de verificação. Você pode confirmar que está fazendo commit das edições corretas e nada extra. E se você decidir que um experimento não funcionou, pode descartar edições não enviadas antes que elas cheguem ao repositório. Isso mantém seu histórico compartilhado limpo. A exploração local permanece local até que você decida enviá-la.
Projetos com escopo de branch e repositório com permissões de equipe
Um projeto Spec-First não flutua no abstrato. Você o cria a partir de um repositório específico e de uma branch específica, geralmente `main`. Esse escopo significa que o projeto sempre aponta para um lugar real no Git. Sua especificação, seu histórico e sua branch se alinham.
As permissões de equipe são configuradas durante a instalação. Você decide quem pode acessar o projeto e o que eles podem fazer, para que as pessoas que trabalham no contrato sejam as pessoas que você pretende. Como o projeto está vinculado a um repositório e uma branch, seu modelo de acesso pode espelhar o modelo de acesso que você já aplica no Git.
Como configurar o Modo Spec-First
A configuração é um fluxo curto e linear. Siga estes passos. O passo a passo oficial está em docs.apidog.com/spec-first-mode-beta-2058268m0 se você quiser capturas de tela junto.
- Mude o modo. Abra o módulo de APIs no Apidog. Encontre o botão de alternância de modo no canto inferior esquerdo do módulo e mude de Modo Design-First para Modo Spec-First.
- Conecte seu provedor Git. Autorize GitHub ou GitLab diretamente. Para Azure DevOps, configure uma Conexão Git genérica com suas credenciais Git.
- Crie um projeto a partir do seu repositório. Escolha o repositório que contém sua especificação e selecione a branch, normalmente `main`. O Apidog delimita o novo projeto a esse repositório e branch.
- Configure as permissões da equipe. Durante a configuração, defina quem pode acessar o projeto e o que eles podem fazer.
- Edite a especificação. Abra seu `openapi.yaml` ou `openapi.json` no editor estilo IDE. Use o esboço à esquerda para navegar. Conte com a validação e o preenchimento automático enquanto escreve.
- Faça commit das suas alterações. Escreva uma mensagem de commit clara. Revise as alterações rastreadas primeiro. Descarte qualquer coisa que você não queira manter.
- Envie para o repositório. Envie seu commit para a branch conectada.
- Verifique a sincronização. Verifique o indicador de status de sincronização. Quando ele indicar “Sincronizado agora”, sua especificação e repositório correspondem.
Esse é o ciclo completo: alternar, conectar, criar, editar, commitar, enviar, verificar.
Um fluxo de trabalho diário típico
Veja como o modo funciona na prática depois de configurado.
Você começa o dia puxando as últimas atualizações da branch conectada, para que seu editor reflita o que seus colegas de equipe mesclaram durante a noite. Você abre o esboço, clica na operação em que está trabalhando e começa a editar o YAML. Um novo endpoint precisa de um corpo de requisição, então você define um esquema. O preenchimento automático ajuda você a acertar os nomes dos campos, e a validação detecta um erro de digitação em um `$ref` antes que se torne um problema.
Quando o endpoint estiver bom, você verifica o rastreamento de alterações do arquivo. Ele mostra suas modificações. Você escreve uma mensagem de commit como `Adicionar endpoint POST /invoices`, faz o commit e o envia. O indicador de status muda para “Sincronizado agora”. Um colega de equipe revisa a alteração em um pull request normal, porque a especificação vive no Git como todo o resto.
Aqui está o tipo de adição que você faria nesse 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]
Todo o ciclo permanece dentro das ferramentas em que você confia. A especificação é código, e você a trata como código.
Quem deve usar o Modo Spec-First
O Modo Spec-First se encaixa melhor em algumas equipes do que em outras. Seja honesto sobre qual você é.
Use o Modo Spec-First se sua equipe já vive no Git. Se você revisa contratos de API em pull requests, se você quer a especificação versionada junto ao seu código de serviço, ou se seus engenheiros preferem editar YAML diretamente, este modo remove atritos. É uma ótima opção para equipes de backend e plataforma que tratam o documento OpenAPI como um artefato de primeira classe.
Escolha o Modo Design-First se você deseja uma experiência visual e guiada. Equipes com não-engenheiros contribuindo para o design, ou qualquer pessoa que prefira clicar em formulários em vez de escrever YAML, avançarão mais rapidamente lá. Equipes mistas onde produto e design opinam sobre os endpoints geralmente preferem o editor visual. Não há resposta errada. Escolha o modo que corresponde à forma como sua equipe realmente trabalha. Nossa postagem de comparação aprofunda-se nesta decisão.
Limitações e observações da versão beta
O Modo Spec-First é uma versão beta. Essa palavra está realizando um trabalho real, então ajuste suas expectativas de acordo.
Como uma versão beta, o modo ainda está amadurecendo. As funcionalidades e o comportamento podem mudar à medida que o Apidog refina o modo com base no feedback. A integração direta com provedores abrange GitHub e GitLab hoje, enquanto o Azure DevOps depende da Conexão Git genérica em vez de uma integração dedicada. Se sua equipe depende de um provedor ou fluxo de trabalho Git específico, confirme se ele atende às suas necessidades antes de comprometer um projeto crítico com o modo.
Como a especificação sincroniza com um repositório ativo, a disciplina Git normal se aplica. Faça commit deliberadamente, envie intencionalmente e use a opção de descarte quando uma edição não deve ser publicada. O rastreamento de alterações de arquivo e o indicador de sincronização estão lá para mantê-lo seguro, mas a responsabilidade por um histórico limpo ainda é sua. Trate a versão beta da mesma forma que você trataria qualquer nova ferramenta que afete sua branch principal: experimente primeiro em um repositório não crítico e, em seguida, expanda quando confiar no fluxo.
A vantagem de uma versão beta é a influência. O feedback inicial molda para onde o recurso se direciona, então, se algo estiver faltando para o seu fluxo de trabalho, vale a pena relatar.
FAQ
O Modo Spec-First é gratuito?
O Modo Spec-First é um recurso beta dentro do Apidog. O acesso segue seu plano Apidog, então verifique a disponibilidade do modo em relação ao seu plano atual e ao status beta. Por estar em beta, o caminho mais simples é habilitá-lo no módulo de APIs e ver se está disponível para sua conta.
Quais provedores Git são suportados?
GitHub e GitLab são suportados através de integração direta. O Azure DevOps funciona via uma Conexão Git genérica, que usa credenciais Git padrão para apontar o Apidog para o seu repositório. Outros hosts Git também podem funcionar através dessa conexão genérica, já que ela depende do Git padrão em vez de uma API específica do provedor.
Posso voltar para o Modo Design-First?
Sim. O botão de alternância de modo fica no canto inferior esquerdo do módulo de APIs, e você alterna entre Spec-First e Design-First lá. Você não está preso. Escolha o modo que melhor se adapta ao projeto em questão.
Quais formatos de arquivo posso editar?
Você edita seu documento OpenAPI como YAML ou JSON bruto no editor estilo IDE. O editor oferece realce de sintaxe, validação de esquema e preenchimento automático para OpenAPI e Swagger, para que você permaneça correto ao escrever em qualquer um dos formatos.
O que acontece com minhas edições não enviadas?
Edições não enviadas permanecem locais até que você as envie. O Modo Spec-First rastreia cada alteração como modificada, adicionada ou excluída, e o indicador de sincronização mostra quando você tem trabalho que ainda não chegou ao repositório. Se você decidir contra uma alteração, descarte-a antes de enviar e ela nunca entrará no seu histórico compartilhado.
Conclusão
O Modo Spec-First do Apidog reúne o editor OpenAPI e o Git em um só lugar. Você edita a especificação como YAML ou JSON, navega por ela através de um esboço analisado automaticamente, valida enquanto digita e sincroniza nos dois sentidos com GitHub, GitLab ou Azure DevOps. Mensagens de commit, envio, rastreamento de alterações e um indicador de sincronização claro oferecem o fluxo de trabalho Git que você já conhece, aplicado ao seu contrato de API.
É uma versão beta, e é voltada para equipes Git-nativas que desejam que a especificação seja código-fonte. Se esse é o seu caso, o modo vale a pena ser analisado seriamente. Habilite-o no módulo de APIs, conecte um repositório e experimente um pequeno ciclo de edição-commit-envio para sentir o fluxo. Quando estiver pronto, experimente o Modo Spec-First na documentação e conecte-o a um repositório em que você confia.