DEV Community

Cover image for Como Projetar APIs Pela CLI
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Projetar APIs Pela CLI

A maioria dos tutoriais de design de API começa com um mouse: abra um editor visual, arraste esquemas, clique para adicionar campos. Esse fluxo funciona, mas não acompanha equipes que mantêm contratos no Git, revisam mudanças em pull requests e executam validações no CI. Se a sua API é entregue como código, projete-a da mesma forma: no terminal, em arquivos de texto e com comandos scriptáveis.

Experimente o Apidog hoje

Projetar APIs pela linha de comando permite criar o contrato, aplicar lint, agrupar arquivos e gerar stubs sem sair do shell. Cada etapa é reproduzível localmente e no pipeline. Isso também facilita a colaboração: colegas, scripts e agentes de IA podem executar os mesmos comandos, sem depender de uma sequência de cliques em uma interface gráfica.

Este guia mostra duas abordagens:

  1. Uma pilha aberta: OpenAPI + Spectral + Redocly CLI + openapi-generator.
  2. O Apidog CLI, que gerencia esquemas, endpoints e autenticação dentro de um projeto acessível pelo terminal.

Para contexto adicional, consulte os guias sobre como projetar uma API e como projetar APIs REST.

Se for usar o Apidog, instale o binário e autentique-se primeiro. O guia de instalação do Apidog CLI cobre o comando npm install -g apidog-cli e o login com token. Para ver todos os grupos de comandos, consulte o guia completo do Apidog CLI.

A rota aberta: criar, validar, agrupar e gerar

A abordagem clássica combina ferramentas independentes. Você mantém a definição OpenAPI sob controle de versão e executa cada ferramenta como uma etapa explícita do fluxo. É um fluxo de trabalho de design de API nativo do Git: simples de revisar, fácil de automatizar e portátil.

1. Crie o documento OpenAPI

Comece com um arquivo YAML. Qualquer editor de texto funciona.

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]
Enter fullscreen mode Exit fullscreen mode

Conforme a API crescer, divida schemas, paths e parâmetros em arquivos separados usando $ref. Isso melhora a legibilidade e reduz conflitos em pull requests.

Uma estrutura comum é:

.
├── openapi.yaml
├── paths/
│   └── orders.yaml
└── schemas/
    └── order.yaml
Enter fullscreen mode Exit fullscreen mode

2. Execute lint com Spectral

Uma especificação escrita manualmente pode perder operationId, documentar respostas de forma inconsistente ou adotar convenções diferentes entre endpoints. Execute um linter antes da revisão de código.

Instale e rode o Spectral:

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

O Spectral informa a linha, a severidade e a regra que falhou. No CI, o código de saída diferente de zero pode interromper a build.

Alternativas incluem o Redocly CLI e o vacuum. O vacuum é rápido e pode ser usado como linter compatível com Spectral. Independentemente da ferramenta, mantenha o lint como uma etapa dedicada do pipeline.

3. Agrupe arquivos com o Redocly CLI

Ferramentas de geração e publicação normalmente precisam de um documento OpenAPI único. Use redocly bundle para resolver $ref e gerar um artefato autocontido.

npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Use o arquivo agrupado como entrada para geração de código, documentação e validações downstream.

O Redocly CLI também suporta lint e pré-visualização. Consulte a documentação oficial do Redocly CLI para ver todos os comandos disponíveis.

4. Gere stubs com openapi-generator

Com uma especificação limpa e agrupada, gere o esqueleto do servidor ou SDKs de cliente.

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Troque -g spring pelo gerador necessário, por exemplo:

# Python com Flask
-g python-flask

# Servidor Go
-g go-server
Enter fullscreen mode Exit fullscreen mode

O resultado é um scaffolding alinhado ao contrato OpenAPI.

Quando usar essa rota

A pilha aberta funciona bem quando sua equipe quer controle máximo sobre:

  • layout de arquivos;
  • regras de lint;
  • etapa de bundle;
  • configuração do gerador;
  • artefatos produzidos no CI.

O custo é manter a integração entre as ferramentas e suas configurações.

A rota do Apidog CLI: design em um único projeto

O Apidog CLI centraliza esquemas, endpoints, pastas, mocks e autenticação em um projeto gerenciado pelo terminal.

O CLI inclui grupos de comandos para:

  • schema para modelos de dados;
  • endpoint para operações;
  • folder para organização;
  • security-scheme para autenticação;
  • import e export para interoperabilidade;
  • mock e outros recursos de projeto.

O Apidog não substitui um linter OpenAPI. Ele não aplica um guia de estilo nem identifica violações de regras de design. Se você precisa de lint, mantenha Spectral ou vacuum no pipeline.

O Apidog também não é de código aberto; é um produto comercial com nível gratuito. A troca é reduzir a “cola” entre ferramentas de design. Veja mais contexto no guia sobre alternativas ao Swagger para design e teste de APIs.

1. Instale e autentique o CLI 

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Consulte o guia de instalação para a configuração do token.

Os comandos retornam JSON estruturado. Muitas respostas incluem agentHints.nextSteps, com sugestões do próximo comando a executar. Para descobrir flags e subcomandos:

apidog --help
apidog schema --help
Enter fullscreen mode Exit fullscreen mode

2. Defina modelos de dados com apidog schema

Comece pelos dados reutilizáveis. Um schema como Order se torna a fonte de verdade para endpoints que o referenciam, equivalente a components/schemas no OpenAPI.

apidog schema --help
apidog schema create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Como a saída é JSON, você pode processá-la com jq e usar IDs retornados no próximo comando.

Se já existir uma definição OpenAPI, importe-a em vez de recriar os recursos manualmente:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

O apidog import aceita OpenAPI 3.x, Swagger 2.0, Postman e Apidog.

3. Defina endpoints com apidog endpoint

Depois de criar os schemas, adicione as operações e associe-as aos recursos do projeto.

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

A saída JSON de endpoint list também pode ser usada em scripts. Por exemplo, você pode comparar endpoints entre branches ou verificar se caminhos críticos possuem as respostas esperadas.

Organize operações relacionadas em pastas:

apidog folder --help
Enter fullscreen mode Exit fullscreen mode

Isso mantém o projeto navegável à medida que a API cresce.

4. Defina autenticação com apidog security-scheme

Autenticação é parte do contrato. Defina chaves de API, bearer tokens ou OAuth 2.0 no nível do projeto e reutilize a configuração nos endpoints.

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

Esse modelo corresponde a components/securitySchemes no OpenAPI, permitindo importação e exportação consistentes.

Evite redeclarar autenticação em cada operação. Definir o esquema uma vez reduz divergências entre endpoints.

5. Valide arquivos de recurso com cli-schema validate

Antes de aplicar mudanças no projeto ou executar o CI, valide a estrutura dos arquivos de definição usados pelo CLI.

apidog cli-schema --help
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

Adicione essa validação como proteção no pipeline:

apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

Se o comando retornar um código diferente de zero, interrompa a execução antes de aplicar um recurso inválido.

apidog cli-schema validate valida a estrutura de recursos do CLI. Ele não substitui lint de estilo OpenAPI. Use Spectral ou vacuum para regras de design, nomenclatura e documentação.

6. Exporte para OpenAPI

Depois de projetar no Apidog, exporte um artefato padrão para o restante da sua toolchain.

apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

O apidog export também pode gerar HTML, Markdown ou Postman.

Com o arquivo OpenAPI exportado, você pode:

# Aplicar regras de estilo
spectral lint dist/openapi.yaml

# Gerar um documento único
redocly bundle dist/openapi.yaml -o dist/openapi.bundled.yaml

# Gerar código
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

A exportação é a ponte entre um projeto integrado e ferramentas abertas.

Conectando o fluxo ao CI

As duas rotas funcionam bem no CI porque cada etapa produz saída textual e código de saída.

Um fluxo mínimo pode validar estilo, validar recursos do CLI e agrupar o contrato:

# Falha em violações de estilo OpenAPI
spectral lint openapi.yaml

# Valida arquivos usados pelo Apidog CLI
apidog cli-schema validate --file resource.json

# Gera um artefato único para as próximas etapas
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Se você usa o Apidog CLI, a saída JSON e agentHints.nextSteps também facilitam a automação por scripts e agentes de codificação. O processo não depende de interpretar uma interface gráfica: o que uma pessoa executa no terminal, um agente ou pipeline também consegue executar.

Armadilhas comuns

Arquivos divididos quebram ferramentas downstream.

Arquivos com muitos $ref são melhores para manutenção humana, mas geradores e ferramentas de publicação frequentemente precisam de um documento único. Execute redocly bundle antes de gerar código ou publicar documentação.

Esperar que o Apidog faça lint.

O Apidog gerencia recursos de projeto; ele não impõe regras de estilo OpenAPI. Mantenha Spectral ou vacuum no fluxo.

Confundir cli-schema validate com lint.

Esse comando valida a estrutura de um recurso do CLI, não convenções de estilo, descrições ausentes ou regras OpenAPI.

Editar um projeto vazio sem importar a API existente.

Se a API já existe em OpenAPI, Swagger ou Postman, importe a definição antes de começar a editar:

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Definir autenticação por endpoint.

Crie um security-scheme no nível do projeto e referencie-o. Repetir a configuração em cada operação aumenta a chance de inconsistência.

Conclusão

Projetar APIs pela CLI transforma uma atividade baseada em cliques em comandos repetíveis e automatizáveis.

A rota aberta usa:

  1. OpenAPI para o contrato;
  2. Spectral para lint;
  3. Redocly para bundle;
  4. openapi-generator para stubs.

A rota do Apidog CLI mantém schemas, endpoints e autenticação em um projeto integrado, com respostas JSON úteis para automação. Você ainda pode exportar OpenAPI e usar Spectral, Redocly ou openapi-generator quando necessário.

Escolha a abordagem compatível com a forma como sua equipe trabalha. Se você já usa Git e ferramentas especializadas, mantenha a pilha e produza artefatos OpenAPI portáveis. Se preferir reduzir a manutenção entre ferramentas, baixe o Apidog, instale o CLI e projete sua próxima API sem depender de um mouse.

Top comments (0)