DEV Community

Cover image for Ferramentas CLI Open Source Gratuitas para Design de API
Lucas
Lucas

Posted on • Originally published at apidog.com

Ferramentas CLI Open Source Gratuitas para Design de API

O design de uma API começa no arquivo de especificação, muito antes do primeiro deploy. Regras de estilo esquecidas, esquemas inconsistentes e mudanças disruptivas ficam muito mais caros depois que chegam aos clientes. Com CLIs na sua máquina e na CI, você detecta esses problemas no pull request, sem depender de uma interface gráfica.

Experimente o Apidog hoje

Este artigo foca na cadeia de ferramentas de código aberto para especificações OpenAPI: ferramentas gratuitas, licenciadas de forma permissiva e que você pode fixar em uma versão, executar offline e usar em qualquer pipeline. Para o contexto completo do processo, veja o guia sobre como projetar uma API.

Você verá seis ferramentas para tarefas complementares:

  • aplicar regras de estilo;
  • executar lint rapidamente em especificações grandes;
  • validar e empacotar arquivos com $ref;
  • gerar SDKs, stubs e documentação;
  • detectar mudanças disruptivas entre versões.

Todas trabalham com a Especificação OpenAPI, então a saída de uma ferramenta pode alimentar a próxima etapa do pipeline.

Nota sobre o Apidog: o Apidog aparece como uma opção complementar, mas não é código aberto e não substitui um linter OpenAPI. As ferramentas das seções seguintes formam a cadeia de ferramentas open source.

O que considerar em uma CLI de código aberto para design de API

Para usar uma ferramenta no fluxo de design de APIs, verifique três pontos.

  1. Licença: prefira licenças permissivas, como MIT e Apache-2.0, ou uma licença copyleft clara. Isso permite uso comercial sem cobrança por usuário.
  2. Execução local e controle de versão: a ferramenta deve funcionar offline, em contêineres e em executores isolados de CI. Fixe versões para garantir resultados reproduzíveis.
  3. Manutenção: verifique commits recentes, changelog público e atividade nas issues. Uma licença MIT não torna, por si só, um projeto uma boa escolha de longo prazo.

A seguir, veja como instalar e aplicar cada ferramenta.

Spectral: transforme seu guia de estilo em regras executáveis

Spectral, da Stoplight, é um linter Apache-2.0 para OpenAPI 3.x, OpenAPI 2.0, AsyncAPI e Arazzo. Ele executa regras definidas em YAML, JSON ou JavaScript.

Instale e execute o lint básico:

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

Por padrão, o conjunto de regras oas detecta problemas como descrições ausentes, exemplos inválidos e erros estruturais.

O uso mais útil é codificar convenções da equipe. Crie um arquivo .spectral.yaml no repositório:

extends:
  - spectral:oas

rules:
  operation-operationId:
    description: Toda operação deve declarar operationId
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  path-kebab-case:
    description: Caminhos devem usar kebab-case
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: '^/([a-z0-9]+(-[a-z0-9]+)*/?)*$'
Enter fullscreen mode Exit fullscreen mode

Execute o conjunto de regras personalizado:

spectral lint openapi.yaml --ruleset .spectral.yaml
Enter fullscreen mode Exit fullscreen mode

Use o Spectral quando você precisa garantir, por exemplo:

  • operationId em todos os endpoints;
  • respostas de erro padronizadas;
  • nomes consistentes em caminhos e schemas;
  • descrições obrigatórias para parâmetros e operações;
  • exemplos válidos para payloads.

Melhor para: aplicar o guia de estilo da equipe como código.

Limitação: valida uma única especificação; não compara versões. Combine-o com oasdiff para identificar mudanças disruptivas.

vacuum: lint compatível com Spectral e focado em velocidade

vacuum é um linter em Go, licenciado sob MIT e compatível com conjuntos de regras do Spectral. Isso permite reutilizar regras existentes com uma execução rápida, especialmente útil em hooks de pré-commit e CI.

Instale e execute:

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

A flag -d mostra detalhes por regra. Para reutilizar um ruleset do Spectral:

vacuum lint --ruleset .spectral.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Como o vacuum é um binário compilado, ele evita o tempo de inicialização do Node e funciona bem em imagens de contêiner pequenas.

Você também pode usar a ferramenta para produzir relatórios a partir da especificação, mantendo a validação próxima do fluxo de documentação.

Melhor para: lint rápido de especificações grandes usando regras Spectral existentes.

Limitação: a maior parte da documentação e do ecossistema de rulesets ainda gira em torno do Spectral. Na prática, muitas equipes escrevem regras para Spectral e as executam com vacuum.

Redocly CLI: valide e empacote especificações multi-arquivo

Redocly CLI, sob licença MIT, combina lint e bundling. Seu principal uso é resolver referências $ref e gerar um documento OpenAPI único a partir de uma estrutura dividida em vários arquivos.

Instale:

npm install -g @redocly/cli
Enter fullscreen mode Exit fullscreen mode

Valide a especificação:

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Empacote uma especificação modular:

redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Uma estrutura comum de projeto pode ser:

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    ├── schemas/
    │   ├── User.yaml
    │   └── Order.yaml
    └── responses/
        └── Error.yaml
Enter fullscreen mode Exit fullscreen mode

No arquivo raiz:

paths:
  /users:
    $ref: ./paths/users.yaml

components:
  schemas:
    User:
      $ref: ./components/schemas/User.yaml
Enter fullscreen mode Exit fullscreen mode

Essa organização mantém diffs menores e reduz conflitos de merge, o que ajuda em um fluxo de trabalho de design de API nativo do Git. O comando bundle transforma a fonte modular no artefato único consumido pela CI, por mocks, geradores de SDK ou sites de documentação.

Melhor para: especificações com múltiplos arquivos e $ref.

Limitação: as regras padrão de lint são mais leves que um ruleset Spectral personalizado. É comum usar Redocly para bundling e Spectral ou vacuum para regras de estilo mais rigorosas.

openapi-generator: gere SDKs, stubs e documentação

openapi-generator, licenciado sob Apache-2.0, gera SDKs de cliente, stubs de servidor e documentação em diversas linguagens a partir de uma especificação OpenAPI.

Instale a CLI:

npm install -g @openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Gere um cliente TypeScript com Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Troque o gerador com -g conforme sua stack:

# Cliente Go
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Cliente Python
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Stub de servidor Java
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server
Enter fullscreen mode Exit fullscreen mode

Inclua a geração no pipeline após validar e empacotar a especificação:

redocly bundle openapi/openapi.yaml -o dist/openapi.yaml
spectral lint dist/openapi.yaml
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Esse fluxo mantém os clientes alinhados ao contrato, seguindo uma abordagem schema-first e contract-driven. Para mais contexto, consulte os princípios de design de API.

Melhor para: manter SDKs, stubs e documentação sincronizados com a especificação.

Limitação: requer JDK 11 ou superior. O código gerado é uma base e pode exigir customização; a qualidade varia por gerador e linguagem de destino.

oasdiff: bloqueie mudanças disruptivas no pull request

Um linter verifica se a especificação segue regras. Ele não informa, por exemplo, que remover um campo de resposta quebrou todos os clientes existentes.

oasdiff é uma ferramenta em Go sob Apache-2.0 para comparar duas versões de uma especificação OpenAPI e identificar alterações, incluindo mudanças disruptivas.

Instale:

go install github.com/oasdiff/oasdiff@latest
Enter fullscreen mode Exit fullscreen mode

Compare versões e mostre apenas mudanças incompatíveis:

oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Outros comandos úteis:

# Lista de mudanças legível por humanos
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Delta detalhado e legível por máquina
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Em uma verificação de pull request, compare a especificação da branch atual com a branch principal:

git show origin/main:openapi.yaml > /tmp/openapi-main.yaml
oasdiff breaking /tmp/openapi-main.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Se o comando retornar uma mudança incompatível, faça a CI falhar. Assim, remover endpoints, tornar campos obrigatórios ou alterar contratos deixa de ser uma surpresa em produção.

Melhor para: detectar mudanças disruptivas antes do merge.

Limitação: compara especificações, não a implementação em execução. Sua utilidade depende de manter o contrato OpenAPI atualizado.

Optic: lint e comparação em uma CLI, com ressalva de manutenção

Optic é licenciado sob MIT e combina lint e comparação de especificações. Ele pode comparar versões de OpenAPI para identificar mudanças disruptivas enquanto aplica regras de estilo.

Instale e compare:

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

O Optic também podia gerar uma especificação a partir de tráfego de teste observado.

No entanto, há uma ressalva importante: o repositório público do Optic foi arquivado no início de 2026 e o projeto não é mais mantido ativamente. O código MIT ainda pode ser usado, mas não recebe novas regras nem patches de segurança.

Melhor para: equipes que já possuem Optic em seus pipelines.

Limitação: projeto legado a partir do início de 2026. Para novas integrações de detecção de mudanças disruptivas, prefira oasdiff.

Onde o Apidog se encaixa — e onde não

O Apidog não é código aberto e não executa lint de OpenAPI ou aplica regras de estilo. Para isso, use Spectral, vacuum ou Redocly CLI.

O Apidog é uma opção integrada para desenhar endpoints e schemas, além de exportar o resultado para OpenAPI. Depois da exportação, você pode enviar a especificação para Spectral, Redocly, openapi-generator e oasdiff.

Instale a CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Autentique e exporte uma especificação:

apidog login --with-token <SEU_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

A CLI inclui grupos de comandos para:

  • endpoint
  • schema
  • mock
  • import
  • export

Um fluxo possível é exportar o contrato e executá-lo na cadeia open source:

apidog export --format openapi -o openapi.yaml
spectral lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml
oasdiff breaking previous-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Veja o guia completo da Apidog CLI para os comandos disponíveis.

Como escolher as ferramentas

Combine as ferramentas com a tarefa. Em vez de buscar uma única CLI para tudo, monte uma cadeia pequena e previsível.

Ferramenta Melhor para Instalação Código aberto? Observações
Spectral Aplicar guia de estilo npm i -g @stoplight/spectral-cli Sim, Apache-2.0 Linter de referência com regras personalizadas
vacuum Lint rápido em escala brew install --cask daveshanley/vacuum/vacuum Sim, MIT Compatível com rulesets Spectral e escrito em Go
Redocly CLI Bundling e validação npm i -g @redocly/cli Sim, MIT Ideal para especificações multi-arquivo com $ref
openapi-generator SDKs, stubs e docs npm i -g @openapitools/openapi-generator-cli Sim, Apache-2.0 Requer JDK 11+
oasdiff Mudanças disruptivas go install github.com/oasdiff/oasdiff@latest Sim, Apache-2.0 Ferramenta mantida para verificações de PR
Optic Lint e comparação npm i -g @useoptic/optic Sim, MIT Repositório arquivado no início de 2026
Apidog CLI Design integrado e exportação npm i -g apidog-cli Não, possui nível gratuito Não é linter; exporta OpenAPI

Uma pilha prática para a maioria dos projetos:

Spectral ou vacuum  -> regras de estilo
Redocly CLI         -> bundle da especificação
oasdiff             -> mudanças disruptivas
openapi-generator   -> clientes, stubs e documentação
Enter fullscreen mode Exit fullscreen mode

Para executar isso em CI, o fluxo pode ser:

# 1. Validar estilo
spectral lint openapi/openapi.yaml --ruleset .spectral.yaml

# 2. Gerar artefato único
redocly bundle openapi/openapi.yaml -o dist/openapi.yaml

# 3. Bloquear incompatibilidades
oasdiff breaking previous/openapi.yaml dist/openapi.yaml

# 4. Gerar SDK
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o generated/client
Enter fullscreen mode Exit fullscreen mode

Para explorar outras opções além da CLI, consulte o guia de alternativas ao Swagger para design e teste de API e os fundamentos de como projetar APIs REST.

Conclusão

A cadeia de ferramentas open source para design de APIs é madura e pode ser executada inteiramente no terminal:

  • Spectral e vacuum aplicam regras de estilo;
  • Redocly CLI empacota especificações modulares;
  • openapi-generator produz clientes, stubs e documentação;
  • oasdiff bloqueia mudanças disruptivas;
  • Optic permanece como opção legada para pipelines existentes.

Conecte essas ferramentas à CI e valide o contrato da sua API a cada push, sem cobrança por usuário e sem depender de um fornecedor.

Se você prefere modelar endpoints e schemas em uma ferramenta integrada e depois exportar OpenAPI para esse mesmo pipeline, baixe o Apidog e experimente o apidog-cli. Ele complementa a cadeia open source, mas não substitui seu linter.

Top comments (0)