A maioria dos tutoriais de design de API começa com um mouse. Abra um editor visual, arraste um esquema para uma tela, clique em caixas de diálogo para adicionar um campo. Isso funciona, mas não se encaixa na forma como muitas equipes realmente entregam. Se a sua definição de API vive no Git, é revisada em pull requests e passa por CI, você quer projetá-la da mesma forma que a implanta: a partir do terminal, em texto, com comandos que você pode scriptar.
Projetar APIs a partir da linha de comando significa que você cria o contrato, o formata de acordo com um guia de estilo (lint), o agrupa em um único arquivo e gera stubs, tudo sem sair do shell. Cada etapa é repetível. Cada etapa pode ser executada em um pipeline. E quando um agente de IA ou um colega de equipe precisa reproduzir sua configuração, eles executam os mesmos comandos que você, em vez de adivinhar quais botões você clicou.
Este guia apresenta duas abordagens. Primeiro, o caminho geral de código aberto, construído a partir de ferramentas de propósito único: crie um arquivo OpenAPI, formate-o com Spectral, agrupe-o com o Redocly CLI e gere stubs de servidor com openapi-generator. Em seguida, o caminho do Apidog CLI, onde o design, esquemas, endpoints e autenticação vivem em um único projeto que você pode gerenciar a partir do terminal. Se você quiser primeiro o pano de fundo conceitual mais aprofundado, leia nosso guia sobre como projetar uma API e o passo a passo sobre projetar APIs REST.
Se você está acompanhando com o Apidog, obtenha o binário primeiro. Nosso guia de instalação do Apidog CLI aborda a etapa npm install -g apidog-cli e o handshake apidog login --with-token, e o guia completo do Apidog CLI mapeia cada grupo de comando.
A rota geral de código aberto: criar, formatar (lint), agrupar (bundle), gerar
A pilha clássica de design de CLI é um conjunto de ferramentas independentes que você conecta. Você mantém sua definição de API em um arquivo OpenAPI sob controle de versão e executa cada ferramenta como uma etapa. Este é o fluxo de trabalho de design de API nativo do Git, e é genuinamente bom. Aqui está o formato dele.
Crie o documento OpenAPI
Você começa com um arquivo YAML simples. Não é necessário nenhum editor especial; qualquer editor de texto funciona. Um openapi.yaml mínimo se parece com isto:
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: An order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
schemas:
Order:
type: object
required: [id, status]
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
À medida que a API cresce, você a divide em vários arquivos e os referencia com $ref. Isso mantém cada esquema legível e revisável por si só.
Formate com Spectral (Lint with Spectral)
OpenAPI escrito à mão pode desviar-se do padrão. Alguém esquece um operationId, outra pessoa deixa uma resposta indocumentada, uma terceira inventa sua própria convenção de nomenclatura. Um linter captura tudo isso antes da revisão. Spectral, da Stoplight, é a escolha padrão. Ele vem com conjuntos de regras para OpenAPI e permite que você escreva os seus próprios.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral imprime cada violação com um número de linha e severidade. Você pode fazer a build falhar em caso de erros verificando o código de saída no CI. O CLI do Redocly e o vacuum fazem o mesmo trabalho se você quiser uma alternativa; o vacuum é rápido e pode ser usado como um linter compatível com Spectral. O ponto permanece independentemente de qual você escolher: a formatação (linting) é uma ferramenta separada e dedicada, e você a executa como uma etapa própria.
Agrupe com o Redocly CLI (Bundle with the Redocly CLI)
Uma vez que sua definição é dividida em vários arquivos, a maioria das ferramentas downstream deseja um único documento autocontido. O Redocly CLI resolve todos os $ref e achata a árvore em um único arquivo.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
O Redocly também formata (redocly lint) e pré-visualiza documentos, então algumas equipes o usam tanto para verificação de estilo quanto para agrupamento. Sua documentação oficial lista o conjunto completo de comandos.
Gere stubs com openapi-generator
Com uma especificação limpa e agrupada, você gera código. O openapi-generator transforma um documento OpenAPI em stubs de servidor, SDKs de cliente e muito mais em dezenas de linguagens.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
Troque -g spring por -g python-flask, -g go-server ou qualquer um dos geradores suportados. Agora você tem um andaime (scaffolding) que corresponde exatamente ao seu contrato.
Essa é a rota aberta de ponta a ponta: quatro ferramentas, quatro comandos, todos scriptáveis. O custo é a interconexão. Você mantém o layout do arquivo, a configuração do linter, a etapa de agrupamento e a configuração do gerador por conta própria, e cada ferramenta tem suas próprias convenções. Funciona bem quando você quer controle máximo e não se importa com a "cola" entre as ferramentas.
A rota do Apidog CLI: design em um único projeto
A outra abordagem mantém o design, esquemas, endpoints, mocks e autenticação dentro de um único projeto que você gerencia a partir do terminal. O binário apidog-cli é um CLI completo para recursos de projeto, não apenas um executor de testes. Ele possui grupos de comandos para toda a superfície de design: schema para modelos de dados, endpoint para operações, folder para organização, security-scheme para autenticação, além de import, export, mock e muito mais.
Uma nota honesta logo de cara: o Apidog não formata seu OpenAPI nem impõe um guia de estilo. Não é para isso que ele serve. Se você precisa de formatação (linting), mantenha o Spectral ou o vacuum em seu pipeline. O Apidog também não é de código aberto; é um produto comercial com um nível gratuito. O que ele oferece é um projeto integrado para que você não precise juntar as peças do design por conta própria. Nossa visão sobre alternativas ao Swagger para design e teste de APIs aborda onde essa troca faz sentido.
Instale e autentique primeiro (consulte o guia de instalação para a configuração do token):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Cada comando retorna JSON estruturado, e a maioria das respostas inclui um bloco agentHints.nextSteps que informa a você (ou a um agente) o que executar em seguida. Adicione --help a qualquer comando para ver suas flags exatas.
Defina modelos de dados com apidog schema
O design começa com seus dados. Um esquema Order reutilizável se torna a única fonte de verdade que os endpoints referenciam, a mesma ideia que components/schemas no OpenAPI puro, mas gerenciado como um recurso de projeto.
apidog schema --help
apidog schema create --project <PROJECT_ID>
Como a saída é JSON, você pode passá-la por jq para pegar o ID do novo esquema e alimentá-lo no próximo comando. Se você já tem um arquivo OpenAPI, importe-o em vez de digitar tudo novamente:
apidog import --project <PROJECT_ID> --file openapi.yaml
apidog import aceita formatos OpenAPI 3.x, Swagger 2.0, Postman e Apidog, então uma definição existente se torna um projeto ativo em uma única etapa.
Defina endpoints com apidog endpoint
Com os modelos no lugar, você adiciona operações. O grupo endpoint cria e atualiza endpoints, conectando-os aos esquemas que você definiu e às pastas que os organizam.
apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Listar endpoints como JSON é útil por si só. Você pode comparar a saída entre branches ou alimentá-la a um script que verifica se cada caminho tem as respostas que você espera. Agrupe endpoints relacionados com o comando folder para que o projeto permaneça navegável à medida que cresce.
Defina autenticação com apidog security-scheme
A autenticação faz parte do contrato, não é um item secundário. O grupo security-scheme define como os clientes autenticam: chaves de API, tokens de portador (bearer tokens), OAuth 2.0 e assim por diante. Isso mapeia para components/securitySchemes no OpenAPI, então a importação e exportação são limpas (round-trip).
apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Definir o esquema uma vez no nível do projeto significa que cada endpoint pode referenciá-lo em vez de cada operação redeclarar sua própria autenticação. Esse é exatamente o tipo de consistência que um linter te cobraria de outra forma.
Valide suas escritas com apidog cli-schema validate
Antes de você commitar mudanças ou entregar um projeto ao CI, você quer saber se suas definições de recursos estão bem-formadas. O CLI oferece um comando cli-schema validate que verifica um arquivo de definição em relação ao esquema que o CLI espera, para que uma escrita malformada falhe rapidamente em vez de passar despercebida.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
Execute isso como uma etapa de guarda em seu pipeline: valide primeiro, depois aplique. Uma saída diferente de zero interrompe o pipeline antes que um recurso inválido chegue ao projeto. Esta é a validação de suas escritas CLI, não a formatação (linting) de estilo OpenAPI; são dois trabalhos diferentes, e você ainda vai querer o Spectral para o segundo.
Exporte de volta para OpenAPI
Projete no Apidog, depois entregue um artefato padrão para o restante do seu conjunto de ferramentas. O apidog export escreve OpenAPI, HTML, Markdown ou Postman.
apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
Agora você está de volta a um arquivo OpenAPI portátil. Alimente-o ao Spectral para formatação (linting), ao openapi-generator para stubs ou em sua build de documentação. O projeto integrado e a pilha de ferramentas abertas não são mutuamente exclusivos; a exportação é a ponte entre eles.
Conectando-o ao CI
Ambas as rotas brilham em um pipeline porque cada comando tem um código de saída e uma saída de texto. Um trabalho mínimo de verificação de design pode executar o linter, depois validar, depois agrupar:
# fail on style violations
spectral lint openapi.yaml
# validate any CLI resource writes before applying
apidog cli-schema validate --file resource.json
# flatten to a single artifact for downstream steps
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Como a saída do Apidog é JSON com agentHints.nextSteps, este fluxo também pode ser conduzido de forma limpa por um agente de codificação de IA. O agente lê o resultado estruturado, vê o próximo passo sugerido e o executa, sem necessidade de 'screen-scraping' de uma GUI. Essa é a principal razão para projetar a partir da CLI em primeiro lugar: o que um humano digita, um script ou um agente também pode digitar.
Armadilhas comuns
Arquivos divididos quebram ferramentas downstream. Uma definição espalhada por muitos arquivos $ref é ótima para humanos e complicada para geradores. Sempre agrupe em um único arquivo antes de gerar código ou publicar docs. redocly bundle é a solução.
Você espera que o Apidog formate (lint). Ele não fará isso. O Apidog gerencia recursos; ele não impõe um guia de estilo nem sinaliza violações de regras do OpenAPI. Mantenha o Spectral ou o vacuum no ciclo para isso. Tratar apidog cli-schema validate como um linter é a confusão comum; ele valida a estrutura do recurso, não o estilo OpenAPI.
Esquecer de importar antes de editar. Se você estiver editando uma API existente através da CLI, importe a definição de origem para o projeto primeiro. Editar um projeto vazio e esperar que seus antigos endpoints estejam lá é uma maneira rápida de ficar confuso.
Autenticação definida por endpoint em vez de uma única vez. Defina um security-scheme no nível do projeto e referencie-o. Redeclarar a autenticação em cada operação é como os contratos divergem.
Concluindo
Projetar APIs a partir da CLI transforma uma tarefa pesada de cliques em um conjunto de comandos repetíveis. A rota aberta, que envolve criar, formatar (lint) com Spectral, agrupar (bundle) com Redocly e gerar com openapi-generator, oferece controle total e nenhuma dependência. A rota do Apidog CLI oferece um projeto integrado onde esquemas, endpoints e autenticação vivem juntos, e cada comando retorna JSON pronto para agentes. A exportação faz a ponte entre os dois, para que você nunca fique preso.
Escolha a rota que se alinha com sua equipe. Se você já vive no Git com uma pilha de ferramentas de propósito único, mantenha-as e adicione apidog export quando quiser um artefato portátil. Se você preferir não manter a "cola" entre as ferramentas, Baixe o Apidog, instale o CLI e projete sua próxima API sem tocar em um mouse.