Se você chegou aqui depois de executar npm install -g @apidevtools/swagger-cli e notou os avisos, aqui está a versão resumida: a ferramenta não é mais mantida. O repositório swagger-cli no GitHub afirma claramente que está obsoleto, citando “o ônus da manutenção de tentar acompanhar as expectativas de uma enorme base de usuários com poucas ou nenhuma contribuição”. O próprio README aponta para o Redocly CLI como o sucessor.
Então você precisa de um substituto. Este texto é especificamente sobre a ferramenta de terminal swagger-cli, aquela que faz validate e bundle. Se você realmente se refere ao Swagger Editor, SwaggerHub, ou ao conjunto de design mais amplo, leia 7 alternativas ao Swagger que também testam sua API em vez disso.
Vamos ver o que o swagger-cli fazia, e então analisar a lista honesta do que usar agora.
O que o swagger-cli realmente fazia
Vale a pena ser preciso, porque o substituto certo depende do que você estava usando.
O swagger-cli tinha exatamente dois comandos:
# Valida uma definição Swagger 2.0 / OpenAPI 3.0 contra o esquema e verifica $refs
swagger-cli validate openapi.yaml
# Segue os ponteiros $ref e combina uma definição multifile em um único arquivo
swagger-cli bundle openapi.yaml -o bundled.json
O comando bundle tinha um pequeno conjunto de opções: -o/--outfile para gravar em um arquivo, -t/--type para escolher JSON ou YAML, -r/--dereference para incluir completamente cada $ref embutido, e -f/--format para indentação.
Essa é a ferramenta completa. Ela validava a estrutura e agrupava especificações multifile. Não realizava linting com regras de estilo, não gerava documentação, não executava testes, nem simulava nada. Se você leu alegações de que o swagger-cli “lintava” sua especificação, elas estão erradas; ele apenas verificava sua definição contra o esquema OpenAPI e resolvia referências. Tenha esse escopo em mente, porque alguns substitutos fazem muito mais, e você pode ou não querer isso.
A lista de opções
Três ferramentas cobrem quase todas as razões pelas quais você usaria o swagger-cli, além de alguns especialistas que merecem menção. Aqui está o resumo honesto.
Redocly CLI: o sucessor oficial e a substituição mais próxima 1:1
Redocly CLI (@redocly/cli, binário redocly) é de código aberto e é a ferramenta para a qual o próprio README do swagger-cli aponta. A Redocly inclusive publica um guia de migração do swagger-cli. Se seu objetivo é um validador e bundler de terminal de fácil substituição, comece aqui.
Instale da mesma forma que você instalou o swagger-cli:
npm install -g @redocly/cli@latest
# ou execute sem instalar
npx @redocly/cli@latest lint openapi.yaml
O mapeamento é direto. O validate do swagger-cli se torna redocly lint, que verifica sua especificação e aplica regras de estilo configuráveis. O bundle do swagger-cli se torna redocly bundle:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
Aqui está o mapeamento das flags de bundle lado a lado:
| swagger-cli | Redocly CLI | Propósito |
|---|---|---|
-o, --outfile |
--output (ou -o) |
Gravar em um arquivo |
-t, --type |
--ext (json, yaml, yml) |
Formato de saída |
-r, --dereference |
-d, --dereferenced |
Incluir completamente todos os $refs embutidos |
Uma coisa a saber: por padrão, o redocly lint faz mais do que o validate do swagger-cli. Ele aplica um conjunto de regras de guia de estilo, não apenas uma verificação de esquema. Se você quer a validação estrutural simples que o swagger-cli oferecia, configure um redocly.yaml com apenas a regra spec, e então execute redocly lint openapi.yaml. Esse comportamento de conjunto de regras é a principal força da Redocly, e não uma desvantagem; é por isso que equipes que desejam governança nativa de terminal gostam dela. Você pode ajustar conjuntos de regras (minimal, recommended, recommended-strict, spec) ou escrever regras personalizadas. Veja a melhor configuração de linter OpenAPI para saber como isso se encaixa com outros linters.
O Redocly CLI também vai além dos dois comandos do swagger-cli. Ele pode split (dividir) uma única descrição em uma estrutura multifile (o inverso do bundle), join (unir) múltiplos arquivos (experimental), e construir documentos HTML Redoc autônomos:
redocly build-docs openapi.yaml -o docs.html
O que ele não faz: executar testes de API ou hospedar um servidor mock. É uma ferramenta de lint/bundle/docs code-first e nativa de terminal, e excelente. Se é tudo o que você precisa, pode parar de ler e migrar hoje.
Apidog: quando você quer mais do que validar e agrupar
Aqui está a reformulação honesta. O swagger-cli era um script estático que você executava para validar e agrupar. Mas para a maioria das equipes, validar e agrupar são meios para um fim. Você valida para que a especificação esteja correta, você agrupa para que seja portátil, e então você simula, testa e documenta. O swagger-cli passava essas etapas posteriores para outras ferramentas.
Apidog preenche essa lacuna. É uma plataforma de API tudo-em-um: design, simulação, teste e documentação em um único workspace, com uma CLI que gerencia importação, exportação e execução de testes de CI. Onde o swagger-cli lhe dava um arquivo, o Apidog lhe oferece um workspace vivo construído a partir desse arquivo.
Os dois comandos que mais diretamente se mapeiam à sua memória muscular do swagger-cli são import e export. Instale a CLI e autentique primeiro:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
Você obtém o token do aplicativo ou da web do Apidog: avatar, depois Configurações da Conta, depois Token de Acesso à API. Ele é armazenado em ~/.apidog/config.toml, então nunca o imprima ou o comite.
Importar é sua etapa de validação. Ele ingere uma definição em um projeto e resolve $refs de múltiplos arquivos em recursos unificados. Se o arquivo estiver malformado, a importação o detecta:
apidog import --project 123456 --format openapi --file ./openapi.json
A importação aceita uma longa lista de formatos além do OpenAPI, incluindo Postman, HAR, Insomnia, WSDL e JSON Schema, o que é útil quando suas fontes são mistas.
Exportar é sua etapa de agrupamento, com um bônus. Ele emite um único arquivo consolidado, e você escolhe a versão OpenAPI na saída. Isso o torna um agrupamento mais uma atualização opcional da especificação em um único comando:
# Agrupar e atualizar para OpenAPI 3.1 em uma só vez
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Ou emitir documentos HTML autônomos
apidog export --project 123456 --format html --output ./docs.html
Para CI, o Apidog adiciona a etapa que o swagger-cli nunca teve: execução de testes.
# Executar um cenário de teste em CI com múltiplos formatos de relatório
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
# Ou executar totalmente offline a partir de um arquivo de coleção exportado
apidog run ./collection.apidog-cli.json
A CLI também gerencia recursos do projeto diretamente, incluindo endpoint, schema, mock, environment, branch, test-suite e test-report. Para detalhes de configuração e todas as flags, veja o guia completo da CLI do Apidog e a documentação oficial da CLI do Apidog.
Agora os limites honestos, porque o encaixe importa mais do que o hype. A CLI do Apidog valida a estrutura na importação, mas não oferece um linter de guia de estilo configurável e code-first com conjuntos de regras personalizadas, como o lint da Redocly faz. Não há comando apidog lint, e você não pode criar regras personalizadas no estilo Spectral através da CLI. Também não há split ou join. Apidog é GUI-first: design, mocking, construção visual de testes e documentação são primariamente criados no aplicativo de desktop ou web, com a CLI gerenciando importação, exportação, execução de testes de CI e gerenciamento de recursos em um projeto. E o Apidog é freemium, não de código aberto, então é um modelo diferente do Redocly CLI e do Spectral.
Spectral: linting puro e personalizável em CI
Se o que você realmente queria do swagger-cli era uma validação rigorosa e com opiniões em seu pipeline, o linter dedicado é o Spectral da Stoplight. É de código aberto e construído para uma única tarefa: aplicar um conjunto de regras personalizável a documentos OpenAPI (e outros JSON/YAML).
O Spectral brilha quando você deseja impor o estilo interno como código, com suas próprias regras, em cada pull request. Ele não agrupa, não gera documentação e não testa endpoints; ele faz lint. Combine-o com um bundler e você terá reconstruído uma versão focada do que o swagger-cli fazia, com governança real. Nosso guia para linting OpenAPI com Spectral aborda a escrita de conjuntos de regras, e validação de OpenAPI em CI cobre como integrá-lo a um pipeline.
Brevemente: openapi-generator e vacuum
Mais duas ferramentas surgem, então aqui está a versão precisa e curta. openapi-generator é um gerador de código e cliente; se sua razão para agrupar era alimentar um gerador, você pode não precisar de uma etapa de agrupamento separada, já que ele consome as especificações diretamente. vacuum é um linter OpenAPI rápido e compatível com Spectral, escrito em Go, uma boa escolha quando a velocidade do lint em grandes monorepositórios é importante. Nenhum deles é um substituto geral de validar-mais-agrupar por si só, mas ambos atendem a necessidades específicas.
Tabela de comparação
Aqui está como as opções se comparam em relação às capacidades que os usuários do swagger-cli tendem a se importar.
| Ferramenta | Validar | Agrupar | Regras de Lint | Docs | Mock | Testar | Código aberto | Melhor para |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | Sim | Sim | Não | Não | Não | Não | Sim (obsoleto) | Nada de novo; não é mantido |
| Redocly CLI | Sim (lint) |
Sim | Sim (configurável) | Sim (Redoc HTML) | Não | Não | Sim | Uma substituição direta de validação/agrupamento no terminal com governança |
| Apidog | Sim (na importação) | Sim (na exportação, com atualização OAS) | Apenas estrutural, sem conjuntos de regras personalizadas | Sim (app + exportar) | Sim | Sim (execução CLI) | Não (freemium) | Uma ferramenta para todo o ciclo de vida da API |
| Spectral | Sim (baseado em lint) | Não | Sim (conjuntos de regras personalizadas) | Não | Não | Não | Sim | Linting rigoroso e personalizável em CI |
| vacuum | Sim (baseado em lint) | Não | Sim (compatível com Spectral) | Não | Não | Não | Sim | Linting rápido em grandes especificações |
A recomendação
Esta não é uma situação de “tudo é ótimo, escolha o seu favorito”. Dois caminhos claros cobrem quase todos.
Escolha o Redocly CLI se você quer uma substituição direta. É o sucessor oficial, é de código aberto, e a migração é quase mecânica: validate para lint, bundle para bundle, com o mapeamento de flags acima. Se o seu fluxo de trabalho é genuinamente apenas “validar e agrupar pelo terminal”, e você gostaria de adicionar regras de governança mais tarde sem mudar de ferramenta, o Redocly é a escolha óbvia. Ele o mantém code-first e nativo de terminal, que é exatamente onde o swagger-cli operava.
Escolha o Apidog se validar e agrupar eram apenas o começo. A maioria das equipes não valida uma especificação por si só. Elas a validam, então alguém precisa de um mock para construir, outra pessoa escreve testes, e alguém é responsável pela documentação. O swagger-cli parava na primeira etapa e fazia você montar o restante a partir do Spectral, um bundler, Postman e Newman. O Apidog integra importação (validação), exportação (agrupamento mais uma atualização de versão OAS), mock, teste e documentação em um único workspace, com uma CLI para as partes que pertencem ao CI. Você para de monitorar um script estático e agora sem manutenção e traz toda a especificação para um lugar onde ela permanece útil depois de agrupada.
Esses são paradigmas diferentes, não versões concorrentes da mesma coisa. O Redocly CLI é o especialista leve, impulsionado por configuração, que você executa puramente do terminal. O Apidog é a plataforma tudo-em-um que por acaso possui uma CLI capaz. Escolha com base em quanto do ciclo de vida você deseja em uma ferramenta, e seja honesto: se você só quer fazer lint e agrupar no terminal, o Redocly é mais enxuto e gratuito.
Se você quiser experimentar a abordagem de ciclo de vida, baixe o Apidog e importe uma especificação existente; é gratuito para começar, sem necessidade de cartão de crédito, e você pode ver sua saída agrupada e versionada em poucos minutos.
FAQ
O swagger-cli ainda é mantido?
Não. O repositório swagger-cli no GitHub está marcado como obsoleto e não é mais mantido, citando baixa contribuição contra uma grande base de usuários. Ele ainda instala e funciona, mas não receberá correções ou atualizações, então planeje uma migração.
O que substituiu o swagger-cli?
O próprio README do projeto aponta para o Redocly CLI como o sucessor. redocly lint substitui swagger-cli validate e redocly bundle substitui swagger-cli bundle. A Redocly inclusive publica um guia de migração dedicado. Se você deseja mais do que validar e agrupar, o Apidog cobre importação, exportação, mock, teste e documentação em um só lugar.
O Apidog é gratuito?
O Apidog é freemium. Existe um plano gratuito que você pode começar sem cartão de crédito, com planos pagos para equipes maiores e necessidades avançadas. Não é de código aberto, o que é a principal diferença em relação ao Redocly CLI e Spectral, caso o licenciamento aberto seja um requisito para você.
Posso manter meu fluxo de trabalho do swagger-cli exatamente como está?
O mais próximo é o Redocly CLI. Para espelhar a validação estrutural simples do swagger-cli, configure um redocly.yaml com apenas a regra spec e execute redocly lint. Para agrupamento, os comandos e flags se mapeiam quase um para um. Para uma análise mais profunda do escopo da ferramenta original, veja como usar o swagger-cli a partir do terminal.