Ferramentas CLI Open Source Gratuitas para Design de API

O design de APIs acontece no seu arquivo de especificação muito antes de qualquer código ser enviado. Uma regra de estilo que você esquece, uma mudança disruptiva que você perde, um esquema que se desvia do que você enviou na semana passada; tudo isso custa mais para corrigir depois. A linha de comando detecta esses problemas onde eles começam, e faz isso na CI sem que ninguém precise clicar em uma interface de usuário.

Esta peça é sobre o lado de código aberto dessa cadeia de ferramentas. Cada ferramenta aqui está disponível sob uma licença permissiva, é gratuita para usar sem custo por usuário e algo que você pode auto-hospedar ou fixar em uma versão que você controla. Isso é importante quando o design da sua API reside em um repositório Git e você quer que as verificações funcionem da mesma forma em cada laptop e em cada pipeline. Se você quiser uma visão mais ampla de como tudo isso se encaixa, comece com nosso guia sobre como projetar uma API, e então volte aqui para escolher as CLIs.

Você obterá seis ferramentas, cada uma com um comando de instalação real e o comando que mostra seu funcionamento: um linter para regras de estilo, uma alternativa rápida baseada em Go, um bundler que também valida, um gerador de código e documentação, e duas ferramentas para detectar mudanças disruptivas entre as versões da especificação. A Especificação OpenAPI é a linguagem comum que todas elas falam, então uma especificação que você analisa com uma ferramenta se encaixa perfeitamente na próxima.

Uma nota honesta logo de cara. O Apidog é destaque aqui, mas não é de código aberto; é um produto comercial com um nível gratuito, e não analisa sua especificação. Então, ele recebe um aparte preciso, não uma entrada de código aberto. As ferramentas abaixo são a verdadeira cadeia de ferramentas de design de código aberto.

O que torna uma ferramenta CLI de código aberto para design de API

Código aberto é uma afirmação específica, não uma sensação. Para esta lista, uma ferramenta se qualifica quando três coisas são verdadeiras.

Primeiro, a licença. Tem que ser uma licença permissiva ou copyleft real que você possa ler; MIT e Apache-2.0 são as duas que você mais verá aqui. Isso é o que permite que você use a ferramenta em um projeto comercial sem uma taxa de licença ou contagem de usuários.

Segundo, auto-hospedagem e controle de versão. Você pode vender o binário, fixar uma versão exata e executá-lo totalmente offline em um executor de CI isolado. Nenhuma ferramenta aqui se conecta a servidores externos ou precisa de uma conta para fazer seu trabalho principal.

Terceiro, manutenção e comunidade. Um repositório com commits recentes, issues abertas que recebem respostas e um changelog público. Um projeto abandonado ainda pode ser licenciado pelo MIT e ainda ser uma má aposta, então sinalizo o status de manutenção onde é importante.

Cada ferramenta abaixo é verificada em relação a esses três pontos. Onde um projeto está parado, você verá isso mencionado.

Spectral: o linter de estilo OpenAPI flexível

Spectral da Stoplight é o linter de código aberto de referência para descrições de API, licenciado sob Apache-2.0. Ele lê um conjunto de regras (um arquivo YAML, JSON ou JavaScript listando suas regras) e o aplica a documentos OpenAPI 3.x, OpenAPI 2.0, AsyncAPI e Arazzo. Se sua equipe tem um guia de estilo de API escrito, Spectral é como você o torna executável.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Pronto para uso, ele vem com um conjunto de regras oas que sinaliza descrições ausentes, exemplos inválidos e problemas estruturais. O verdadeiro valor aparece nas regras personalizadas: exigir um operationId em cada operação, um esquema compartilhado em respostas de erro, uma convenção de nomenclatura em caminhos. Essas regras vivem no seu repositório e são executadas de forma idêntica para cada colaborador.

Melhor em: aplicar um guia de estilo de equipe como código. Limitação honesta: Spectral verifica uma única especificação; ele não compara duas versões, então combine-o com uma ferramenta de comparação para detectar mudanças disruptivas.

vacuum: o linter mais rápido, substituto para conjuntos de regras Spectral

Se Spectral é o padrão, vacuum é a opção de velocidade. É um linter Go, licenciado pelo MIT, 100% compatível com os conjuntos de regras Spectral. Então você pode apontá-lo para o mesmo conjunto de regras que você já escreveu e obter resultados muito mais rapidamente em especificações grandes, que é exatamente o que você quer em um hook de pré-commit ou um ciclo de CI apertado.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

A flag -d fornece uma saída detalhada por regra. vacuum também faz mais do que lint; ele gera relatórios HTML e documentação a partir da mesma especificação. Por ser um único binário compilado sem tempo de execução Node, ele inicia rapidamente e se encaixa perfeitamente em um contêiner.

Melhor em: analisar rapidamente grandes especificações com conjuntos de regras que você já possui. Limitação honesta: o ecossistema de conjuntos de regras e a documentação ainda se concentram no Spectral, então você frequentemente escreverá regras contra o modelo do Spectral e as executará através do vacuum. Isso é um recurso, mas significa que Spectral ainda é a coisa que você aprende primeiro.

Redocly CLI: lint mais bundle em um único binário

Redocly CLI é licenciado pelo MIT e cobre um trabalho ligeiramente diferente. Ele analisa, mas seu destaque é o bundle: ele pega uma especificação dividida em muitos arquivos $ref (a maneira sensata de manter um design de API grande e fácil de manter) e a achata em um único documento para ferramentas que esperam um único arquivo. Ele também gera documentação de referência de API a partir do resultado empacotado.

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

Dividir sua especificação em arquivos por recurso mantém os diffs legíveis e os conflitos de mesclagem pequenos, o que é fundamental para um fluxo de trabalho de design de API nativo do Git. O bundle do Redocly é o passo que transforma essa fonte multifile de volta no artefato único que sua CI, servidor mock ou site de documentação consome.

Melhor em: projetos de especificação multi-arquivo que precisam de empacotamento e uma passagem de validação. Limitação honesta: suas regras de lint padrão são mais leves do que um conjunto de regras Spectral completo e personalizado, então muitas equipes executam o Redocly para empacotamento e o Spectral ou vacuum para aplicação profunda de estilo.

openapi-generator: transforme o design em clientes, stubs e documentos

O design não está finalizado até que outras pessoas possam desenvolver sobre ele. openapi-generator é Apache-2.0 e gera SDKs de cliente, stubs de servidor e documentação a partir de uma especificação OpenAPI em dezenas de linguagens. Tratar a especificação como a fonte da verdade e gerar o resto é o cerne de uma abordagem schema-first e contract-driven, que abordamos em princípios de design de API.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

Troque -g typescript-axios por go, python, java, kotlin, ou qualquer um dos muitos geradores suportados. Execute-o na CI a cada alteração de especificação e suas bibliotecas de cliente nunca se desviarão do contrato.

Melhor em: manter código gerado e documentação em sincronia com o design. Limitação honesta: precisa de um JDK para rodar (JDK 11+), o código gerado é um ponto de partida que você frequentemente personalizará, e a qualidade do gerador varia por linguagem-alvo. Verifique a saída antes de enviá-lo.

oasdiff: detecte mudanças disruptivas antes que cheguem aos clientes

Um linter informa se uma especificação está limpa. Ele não pode dizer que renomear um campo acabou de quebrar todos os clientes em produção. oasdiff é a ferramenta Go Apache-2.0 que preenche essa lacuna: dê a ele duas versões de uma especificação e ele relata as diferenças, e especificamente as mudanças disruptivas.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

O comando breaking mostra apenas as mudanças que quebram os consumidores existentes; changelog fornece uma lista legível por humanos de tudo que mudou, sendo disruptivo ou não; diff fornece o delta completo legível por máquina. Conecte oasdiff breaking em uma verificação de pull-request e uma mudança disruptiva se torna uma falha na construção em vez de um alerta às 3 da manhã.

Melhor em: controlar mudanças disruptivas na CI. Limitação honesta: ele compara especificações, então é tão bom quanto sua disciplina em manter a especificação atualizada com a API real. Ele não analisa estilo; use-o juntamente com Spectral ou vacuum.

Optic: compara e analisa juntos, com uma ressalva de manutenção

Optic é licenciado pelo MIT e faz algo que os outros separam: ele analisa e compara OpenAPI em uma única ferramenta, comparando duas versões para sinalizar mudanças disruptivas enquanto também aplica regras de estilo. Ele poderia até gerar uma especificação a partir do tráfego de teste observado.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

Aqui está a honestidade que uma lista de código aberto lhe deve: o repositório público do Optic foi arquivado no início de 2026 e o projeto não é mais ativamente mantido. A fonte MIT ainda funciona, então você pode usá-lo, mas não receberá novas regras ou patches de segurança. Para detecção de mudanças disruptivas hoje, oasdiff é a opção mantida; Optic permanece na lista porque você ainda o encontrará em pipelines existentes.

Melhor em: equipes já investidas nele, ou qualquer um que queira lint e diff em uma única CLI. Limitação honesta: não é mais mantido a partir do início de 2026; trate-o como legado e planeje um caminho de migração.

Onde o Apidog se encaixa (e onde não)

Apidog não é de código aberto, e não analisa seu OpenAPI nem impõe regras de estilo; Spectral, vacuum e Redocly são seus linters, ponto final. O que o Apidog oferece é uma compensação diferente: em vez de juntar seis binários separados, seu nível gratuito mais o binário apidog-cli oferece um lugar integrado para projetar endpoints e esquemas de dados, e então exportar o resultado como OpenAPI para alimentar diretamente essas verificações de código aberto.

npm install -g apidog-cli
apidog login --with-token <SEU_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

A CLI possui grupos de comandos para endpoint, schema, mock e import/export, então você pode automatizar o design da API pelo terminal e entregar a especificação exportada para o openapi-generator ou oasdiff. Veja o guia completo da Apidog CLI para o conjunto completo de comandos. A contextualização honesta: Apidog é a opção comercial e integrada que se integra bem com a cadeia de ferramentas de código aberto, não um substituto para um linter e não um projeto de código aberto em si.

Como escolher

Combine a ferramenta com a tarefa. A maioria das equipes usa duas ou três delas juntas, não apenas uma.

Uma pilha prática: Spectral ou vacuum para estilo, Redocly para empacotamento, oasdiff para mudanças disruptivas e openapi-generator para produzir clientes. Se manter tantas ferramentas for mais do que você deseja, uma plataforma integrada cobre a parte de design e exportação em um só lugar. Para uma visão mais ampla do cenário de ferramentas além da CLI, consulte nosso guia sobre alternativas ao Swagger para design e teste de API e os fundamentos em como projetar APIs REST.

Conclusão

A cadeia de ferramentas CLI de código aberto para design de API é madura e gratuita para usar: Spectral e vacuum analisam, Redocly empacota, openapi-generator produz clientes e oasdiff protege contra mudanças disruptivas, com Optic como uma opção legada a ser reconhecida. Conecte-os à CI e seu contrato de API será verificado a cada push, sem custo por usuário e sem bloqueio de fornecedor.

Se você preferir projetar endpoints e esquemas em uma ferramenta integrada e exportar OpenAPI limpo para o mesmo pipeline, Baixe Apidog e experimente o apidog-cli; é o companheiro comercial da pilha de código aberto, não um substituto para o seu linter. De qualquer forma, o objetivo é o mesmo: detectar problemas de design no terminal, antes que cheguem aos seus usuários.