Seu código vive no Git. Seus pipelines de CI, revisões e histórico de lançamento vivem no Git. Então, por que sua especificação de API vive em outro lugar?
Um fluxo de trabalho de API Git-nativo mantém sua definição OpenAPI no mesmo lugar que seu código. Você edita a especificação como um arquivo YAML ou JSON simples, o comita e o envia através do mesmo processo de revisão que usa para todo o resto. Sem banco de dados em nuvem separado. Sem malabarismos de exportação-importação. A especificação é apenas mais um arquivo em seu repositório.
O que significa um fluxo de trabalho de API Git-nativo
Um fluxo de trabalho de API Git-nativo trata sua especificação de API como código. O arquivo OpenAPI reside em um repositório junto com seus serviços. Toda mudança é um commit. Cada commit tem um autor, uma mensagem e um diff.
Isso lhe oferece três coisas que você já espera do código-fonte:
- Histórico de versões. Você pode ver quem alterou um endpoint e quando. O
git blamefunciona na sua especificação. - Ramificação e revisão. As mudanças na especificação passam por pull requests. Os revisores veem o diff exato antes de qualquer mesclagem.
- Uma única fonte de verdade. O arquivo em
mainé o contrato. Ferramentas, documentação e mocks leem a partir dele.
Essa é a ideia central por trás de um fluxo de trabalho de API spec-first: a especificação lidera e a implementação segue. Para uma análise mais aprofundada dessa prática, consulte nosso guia sobre desenvolvimento de API spec-first.
A abordagem oposta armazena sua especificação dentro de um aplicativo proprietário na nuvem. Isso funciona até sua equipe crescer ou seu processo amadurecer. Então as falhas aparecem.
O problema com especificações de API bloqueadas na nuvem
A maioria das ferramentas de design de API mantém a especificação em seu próprio banco de dados. Você edita através da UI delas. O “arquivo” que você pensa que possui é, na verdade, uma linha no sistema de outra pessoa.
Isso falha de maneiras previsíveis.
A revisão acontece em dois lugares. As mudanças de código passam pelo GitHub. As mudanças na especificação passam por uma ferramenta separada com seus próprios comentários e histórico. Os revisores trocam de contexto. As aprovações ficam fora de sincronia.
O diff está oculto. Quando a especificação reside em um banco de dados na nuvem, você não consegue ver um diff limpo linha por linha em seu pull request. Você aprova uma “v3 do design” sem ter ideia do que realmente mudou.
A exportação se torna uma tarefa árdua. Para levar a especificação para o CI, você a exporta, comita a exportação e espera que ninguém tenha editado a cópia na nuvem nesse meio tempo. Duas fontes de verdade, um conflito inevitável.
A automação luta contra você. Linters, testes de contrato e geradores de código querem um arquivo em disco. Uma especificação bloqueada na nuvem força uma etapa de busca antes que qualquer um deles seja executado.
Tratar sua especificação de API como código remove tudo isso. O arquivo é a especificação. Git é o histórico. Seu pipeline existente faz o resto. Cobrimos o princípio em detalhes em especificação de API como código.
Como funciona o Modo Spec-First do Apidog
O Modo Spec-First foi construído para equipes que já pensam em commits e branches. Você projeta a API como arquivos YAML ou JSON brutos, e o Apidog mantém esses arquivos sincronizados bidirecionalmente com seu repositório Git.
Aqui está o que você obtém.
Um editor OpenAPI estilo IDE
Você escreve a especificação em um editor de código, não em um formulário. O editor oferece as conveniências que você esperaria de um IDE:
- Destaque de sintaxe para YAML e JSON.
- Validação contra os schemas OpenAPI e Swagger, para que erros apareçam enquanto você digita.
- Preenchimento automático para palavras-chave, tipos e referências OpenAPI.
Você mantém o controle do arquivo exato. Sem campos ocultos, sem metadados apenas da UI.
Arquivos YAML/JSON brutos
A especificação é um arquivo real. Um pequeno trecho de um:
openapi: 3.1.0
info:
title: Orders API
version: 1.2.0
paths:
/orders/{orderId}:
get:
summary: Get an order by ID
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: Order not found
components:
schemas:
Order:
type: object
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
Este é o arquivo que vai para o seu repositório. O que você edita é o que é commitado.
Um esboço navegável analisado automaticamente
Enquanto você digita, o Apidog analisa o arquivo e constrói um esboço visual na barra lateral esquerda. Caminhos, operações e schemas aparecem como uma árvore que você pode clicar. Você obtém a legibilidade de uma ferramenta de design e a precisão de arquivos brutos ao mesmo tempo.
Especificações longas permanecem navegáveis. Salte para um endpoint sem rolar centenas de linhas.
Sincronização Git bidirecional
O Modo Spec-First se conecta ao seu provedor Git e sincroniza as alterações em ambas as direções. Ele suporta GitHub e GitLab diretamente, e Azure DevOps através de uma Conexão Git.
Puxe as alterações que seus colegas de equipe enviaram. Edite localmente no editor Apidog. Em seguida, comite e envie de volta para a mesma branch. O repositório e seu espaço de trabalho permanecem alinhados.
Commit, push e um indicador de status de sincronização
Você não precisa sair do Apidog para gerenciar o Git. Prepare suas alterações (stage), escreva uma mensagem de commit e envie (push). Um indicador de status de sincronização informa onde você está. Após um push bem-sucedido, ele exibe algo como “Sincronizado agora mesmo”. Se você mudar de ideia antes de enviar, pode descartar as edições não enviadas e retornar ao último estado sincronizado.
Essa sincronização bidirecional é o coração do fluxo de trabalho de API Git-nativo. Para um passo a passo focado no lado do GitHub, veja sincronizar especificação OpenAPI com GitHub.
Passo a passo da configuração
Veja como ir de um repositório vazio para uma especificação sincronizada. A referência completa está nos documentos do Modo Spec-First.
- Crie um projeto a partir de um repositório. No Apidog, inicie um novo projeto Spec-First e conecte seu provedor Git. Escolha o repositório que contém sua especificação de API e selecione a branch a ser rastreada, geralmente
main. O Apidog puxa os arquivos de especificação existentes para o editor.
- Edite a especificação. Abra o arquivo OpenAPI no editor. Adicione um endpoint, ajuste um schema ou corrija uma resposta. Destaque de sintaxe, validação e preenchimento automático o guiam enquanto você escreve. O esboço da barra lateral esquerda é atualizado conforme o arquivo muda.
- Rastreie arquivos modificados, adicionados e excluídos. O Apidog mostra quais arquivos você alterou desde a última sincronização. Arquivos modificados, adicionados e excluídos são sinalizados para que você saiba exatamente o que está prestes a ser incluído no commit.
- Escreva uma mensagem de commit. Descreva a mudança em linguagem simples, da mesma forma que faria em qualquer cliente Git. “Adicionar resposta 404 a getOrder” é melhor que “atualizar especificação”.
- Push. Envie o commit para a branch rastreada. Seus colegas de equipe e seu pipeline de CI agora veem a nova versão.
- Verifique “Sincronizado agora mesmo”. Observe o indicador de status de sincronização confirmar o push. Quando ele exibe “Sincronizado agora mesmo”, suas edições locais e a branch remota correspondem. A partir daqui, a alteração flui através do seu processo normal de pull request e revisão.
Esse é o ciclo completo: pull, editar, commit, push, verificar. Sem etapa de exportação. Sem segunda fonte de verdade.
Modo Spec-first vs. Design-first
O Apidog suporta duas formas de trabalho. A diferença está em onde a especificação reside e como você a edita.
| Modo Spec-First (beta) | Modo Design-First | |
|---|---|---|
| Armazenamento da especificação | Arquivos YAML/JSON brutos no Git | Projeto na nuvem Apidog |
| Editor principal | Editor de código estilo IDE | UI visual baseada em formulário |
| Controle de versão | Git nativo (commits, branches, diffs) | Histórico e branches do Apidog |
| Sincronização Git bidirecional | Sim (GitHub, GitLab, Azure DevOps) | Via exportação/importação |
| Melhor para | Equipes que vivem no Git | Equipes que preferem um fluxo de trabalho visual |
Nenhum dos modos é “melhor”. Eles atendem a diferentes hábitos. Se seu processo de revisão e lançamento já roda no Git, o Modo Spec-First remove a complicação. Se sua equipe projeta visualmente e raramente toca em OpenAPI bruto, o Modo Design-First pode ser mais adequado.
Quando usá-lo
Recorra ao Modo Spec-First quando:
- Sua especificação deve passar por pull requests e revisão de código.
- Você deseja o
git blamee um histórico de commit real em seu contrato de API. - Seu CI executa linting de especificação, testes de contrato ou geração de código que precisam de um arquivo em disco.
- Vários engenheiros editam a especificação e você deseja diffs limpos e mescláveis.
- Você está cansado de exportar de uma ferramenta para alimentar outra.
Mantenha uma abordagem visual e cloud-first quando sua equipe projeta APIs sem escrever OpenAPI bruto, ou quando não-engenheiros são os donos da especificação e preferem um editor baseado em formulário.
FAQ
O que é um fluxo de trabalho de API Git-nativo?
Um fluxo de trabalho de API Git-nativo armazena sua especificação OpenAPI como um arquivo em um repositório Git e gerencia cada alteração através de commits, branches e pull requests. A especificação segue o mesmo processo de revisão e controle de versão que o código da sua aplicação, então há uma única fonte de verdade.
O Modo Spec-First do Apidog suporta GitHub e GitLab?
Sim. O Modo Spec-First sincroniza bidirecionalmente com GitHub e GitLab diretamente. O Azure DevOps é suportado através de uma Conexão Git. Você conecta o repositório, escolhe uma branch e o Apidog mantém suas edições e o remoto sincronizados.
Posso editar arquivos OpenAPI como YAML ou JSON brutos?
Sim. O Modo Spec-First oferece um editor estilo IDE para YAML e JSON brutos, com destaque de sintaxe, validação de esquema e preenchimento automático para OpenAPI e Swagger. Um esboço na barra lateral esquerda analisa automaticamente o arquivo para que você possa navegar rapidamente por grandes especificações.
Qual a diferença entre o Modo Spec-First e Design-First?
O Modo Spec-First mantém sua especificação como arquivos no Git e os edita em um editor de código com sincronização bidirecional. O Modo Design-First mantém a especificação em um projeto na nuvem do Apidog com um editor visual baseado em formulário. Escolha o Spec-First se seu fluxo de trabalho já roda no Git.
Conclusão
Um fluxo de trabalho de API Git-nativo encerra a divisão entre seu código e seu contrato de API. A especificação se torna um arquivo, o arquivo se torna um commit, e o commit flui através do processo de revisão no qual você já confia.
O Modo Spec-First do Apidog oferece o editor estilo IDE, o esboço navegável e a sincronização Git bidirecional para tornar isso realidade. Você edita YAML ou JSON brutos, comita uma mensagem clara, faz push e observa o status exibir “Sincronizado agora mesmo”.
Experimente o Modo Spec-First e traga sua especificação de API para casa no Git.