O Redocly CLI é uma ótima ferramenta. Se você já a usou para lintar arquivos OpenAPI, empacotar uma especificação de múltiplos arquivos em um só, ou construir documentação Redoc a partir do terminal, você já sabe disso. Então, por que procurar uma alternativa ao Redocly CLI?
Geralmente, a razão está no escopo. O Redocly CLI é um especialista focado e "code-first": lintar, empacotar, dividir, juntar, construir documentação. Isso é exatamente o que algumas equipes precisam e não é suficiente para outras. Se você quer uma ferramenta que também projeta, simula e testa sua API, o CLI não tenta ser essa ferramenta, e nem deveria.
Este artigo é sobre o Redocly CLI (o pacote de código aberto @redocly/cli), não o produto de documentação hospedado da Redocly. Se você está comparando a plataforma de documentação hospedada ou o próprio Redoc, leia nosso resumo de alternativas ao Redocly para documentação de API. Este post é para pessoas que digitam redocly lint e redocly bundle e querem saber o que mais se encaixa em seu fluxo de trabalho.
O que o Redocly CLI faz bem
O Redocly CLI é de código aberto e nativo do terminal. Você o instala uma vez e obtém um conjunto conciso de comandos que executam suas funções de forma limpa. A documentação do Redocly CLI cobre todos eles, mas aqui está a versão resumida.
A lintagem é sua principal força. redocly lint valida sua descrição OpenAPI, AsyncAPI, Arazzo ou Open-RPC e então executa regras de guia de estilo. Você configura tudo através de um arquivo redocly.yaml: escolha um conjunto de regras integrado (minimal, recommended, recommended-strict, ou spec) ou crie suas próprias regras personalizadas. Essa governança orientada por configuração é difícil de superar se você deseja aplicar um design de API consistente no CI em várias equipes.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
Bundle, split e join lidam com a organização da especificação. redocly bundle segue os ponteiros $ref e produz um arquivo consolidado. redocly split faz o inverso, explodindo uma única descrição em um layout de múltiplos arquivos. redocly join (experimental) mescla múltiplos arquivos OpenAPI em um só.
redocly bundle openapi.yaml --output dist/openapi.json
A documentação vem de build-docs. Ele produz uma página HTML Redoc autônoma, e preview-docs oferece uma pré-visualização local ao vivo.
redocly build-docs openapi.yaml -o docs.html
Então, se suas necessidades são "validar contra um guia de estilo, empacotar a especificação e gerar documentação Redoc, tudo a partir do terminal", o Redocly CLI é uma ótima escolha padrão. Muitas equipes deveriam mantê-lo. As razões para procurar em outro lugar são sobre escopo, não qualidade.
Por que as pessoas procuram uma alternativa
Alguns padrões aparecem repetidamente:
- Você quer uma plataforma completa, não apenas lintagem e documentação. O Redocly CLI não executa testes de API e não hospeda um servidor de mock. Se você também precisa de design, mocking e um executor de testes, você está montando uma cadeia de ferramentas em torno dele.
- Você quer uma GUI junto com o CLI. Redocly é "code-first" por design. Se sua equipe inclui pessoas que preferem trabalhar visualmente, a governança apenas por terminal é uma venda difícil.
- Você quer um executor de testes integrado para CI. A lintagem detecta problemas na especificação. Ela não informa se a API em execução se comporta. Essa é uma ferramenta separada.
- Você não quer juntar cinco ferramentas. Spectral para lintagem, Redocly para empacotamento e documentação, Postman ou Newman para testes, outra coisa para mocks. Isso funciona, mas são muitas partes móveis para manter.
Cada um desses pontos indica uma alternativa diferente. Vamos combiná-las.
A lista resumida, pelo que você realmente queria
Apidog, se você quer uma plataforma para todo o ciclo de vida da API
Apidog é uma plataforma de API "tudo em um": design, mocking, testes e documentação em um só lugar, com um CLI para importação, exportação e execução de testes em CI. É a escolha certa quando você prefere ter uma única ferramenta para todo o ciclo de vida em vez de juntar um linter, um empacotador, um executor de testes e um servidor de mock.
Aqui está a parte honesta. Apidog não possui um linter de guia de estilo configurável e "code-first" com conjuntos de regras personalizadas como o lint do Redocly. Não há comando apidog lint e nenhuma maneira de criar regras personalizadas no estilo Spectral ou Redocly através do CLI. Apidog valida a estrutura ao importar uma especificação, mas se a governança de design estrita e personalizável é a única coisa com a qual você se importa, Apidog não substituirá redocly lint por si só. Combine-o com Spectral para essa tarefa. Voltaremos a isso mais tarde.
O que Apidog oferece que o Redocly CLI não oferece: um designer visual, um servidor de mock integrado, um construtor de testes visual e um executor de testes de CI. O CLI lida com as partes que pertencem a um terminal.
# Install and authenticate (token from the app: avatar > Account Settings > API Access Token)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# Import a spec into a project (validates + resolves multi-file $refs)
apidog import --project 123456 --format openapi --file ./openapi.json
# Export a single consolidated file, and pick your OpenAPI version
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Run a test scenario in CI with multiple report formats
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
apidog import faz o trabalho de validação na ingestão, e apidog export faz um trabalho de empacotamento na saída (ele emite um arquivo e pode atualizar a versão OAS). A lista completa de comandos está na documentação do Apidog CLI, e nosso guia completo do Apidog CLI percorre cada flag. Melhor para: equipes que desejam design, mock, teste e documentação sob o mesmo teto.
Spectral, se tudo o que você queria do Redocly era o linter
Se a única coisa para a qual você usa é o redocly lint, você não precisa mudar de plataforma. O Spectral da Stoplight é o linter de código aberto, baseado em regras, que mais se sobrepõe à lintagem do Redocly. Você escreve regras em YAML, as executa contra qualquer documento OpenAPI ou AsyncAPI, e as integra ao CI.
O linter do Spectral e do Redocly são primos próximos. Ambos são orientados por configuração, ambos fornecem conjuntos de regras, ambos permitem que você crie regras personalizadas. A escolha entre eles geralmente se resume ao ajuste do ecossistema e qual formato de conjunto de regras sua equipe já conhece. Nosso aprofundamento na lintagem OpenAPI com Spectral aborda a criação de regras, e o guia mais amplo sobre lintagem de API compara o cenário de lintagem se você quiser o panorama completo. Melhor para: equipes cuja verdadeira necessidade é uma lintagem de especificação pura e personalizável.
Scalar ou Bump.sh, se você queria principalmente a documentação
Se a parte do Redocly CLI com a qual você se importava era build-docs, a alternativa é uma ferramenta de documentação, não uma plataforma. Scalar e Bump.sh transformam uma descrição OpenAPI em documentação de referência hospedada e navegável, cada uma com seu próprio visual e conjunto de recursos. Eles se concentram na experiência da documentação em vez de lintagem ou testes. Melhor para: equipes cujo objetivo principal é uma documentação de referência de API bonita e de fácil manutenção.
swagger-cli, que não é mais uma opção
Você ainda verá o swagger-cli mencionado em guias antigos, então vale a pena deixar claro: o swagger-cli está obsoleto. O repositório swagger-cli no GitHub afirma que não é mais mantido e direciona os usuários para o Redocly CLI como sucessor.
Ele sempre teve apenas dois comandos, swagger-cli validate e swagger-cli bundle. Nunca fez lintagem com regras de estilo, nunca gerou documentação, nunca executou testes e nunca simulou nada. Se você o usa hoje, a mudança é para fora dele, não para ele. Nosso guia sobre como usar o swagger-cli cobre o que ele fazia, e a Redocly até publica um guia de migração do swagger-cli com o mapeamento exato das flags. Incluiremos esse mapeamento abaixo para fins de completude.
Tabela de comparação
Veja como as opções se alinham com as tarefas que o Redocly CLI gerencia. "Lint custom rules" significa um linter de guia de estilo configurável e "code-first" com conjuntos de regras personalizadas.
| Ferramenta | Lint regras customizadas | Empacotamento | Documentação | Mock | Teste | GUI | Código aberto | Melhor para |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | Sim | Sim | Sim (Redoc) | Não | Não | Não | Sim | Governança de lint, empacotamento e documentação "code-first" a partir do terminal |
| Apidog | Não | Via exportação | Sim | Sim | Sim (Executor CI) | Sim | Não (freemium) | Uma plataforma para design, mock, teste e documentação |
| Spectral | Sim | Não | Não | Não | Não | Não | Sim | Lintagem pura e personalizável de OpenAPI/AsyncAPI |
| Scalar / Bump.sh | Não | Não | Sim | Não | Não | Sim | Varia | Documentação de referência de API hospedada |
| swagger-cli | Não | Sim | Não | Não | Não | Não | Sim (obsoleto) | Nada de novo, não é mais mantido |
Uma nota sobre a tabela: "Via exportação" do Apidog significa que apidog export emite um arquivo consolidado, o que cobre a razão prática pela qual você executaria redocly bundle, mas não é um comando bundle igual. E Apidog é freemium, não código aberto, enquanto Redocly CLI e Spectral são ambos de código aberto. Chame essas trocas pelo que são.
Mapeamento de flags de bundle do swagger-cli para Redocly CLI
Se você está usando o obsoleto swagger-cli e o Redocly é seu destino para empacotamento, as flags se mapeiam de forma limpa:
| swagger-cli | Redocly CLI | Significado |
|---|---|---|
-o, --outfile <file> |
--output (ou -o) |
Gravar em um arquivo em vez de stdout |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
Tipo de arquivo de saída |
-r, --dereference |
-d, --dereferenced |
Incorporar completamente todos os $refs |
Assim, swagger-cli bundle -o output.json se torna redocly bundle --output output.json.
Uma recomendação clara
Não há um único vencedor, porque a resposta certa depende de qual tarefa do Redocly CLI você está tentando substituir.
Mantenha o Redocly CLI se sua governança é exatamente o que você precisa. Um linter, empacotador e construtor de documentação Redoc leve, de código aberto e orientado por configuração que você executa puramente do terminal é uma configuração genuinamente boa. Nada aqui é motivo para abandonar uma ferramenta que se encaixa.
Escolha Apidog se você está cansado de montar uma cadeia de ferramentas e quer design, mocking, testes e documentação em uma única plataforma com um CLI para as partes que se encaixam no terminal. Você para de manter ferramentas separadas para cada etapa e obtém uma GUI para as pessoas da sua equipe que desejam uma. Apenas seja claro que você o combinará com o Spectral se também precisar de lintagem de regras personalizadas. O guia do Apidog CLI em CI/CD mostra como o executor de testes se encaixa em um pipeline, e Apidog CLI vs Newman compara-o com o executor que muitas equipes já usam. Você pode baixar o Apidog e experimentá-lo gratuitamente, sem necessidade de cartão de crédito.
Escolha Spectral se a lintagem é o principal. Não mude de plataforma para substituir um comando.
A verdade é: Redocly é um especialista em CLI "code-first", e Apidog é uma plataforma visual "tudo em um". São paradigmas diferentes, não uma substituição direta. Escolha pelo ajuste.
FAQ
Apidog é uma substituição direta para o Redocly CLI? Não, e é melhor ser direto sobre isso. Apidog cobre mais do ciclo de vida (design, mock, teste, documentação), mas não possui um linter de regras personalizadas como o redocly lint. Se a governança de especificação estrita e configurável é sua principal tarefa, mantenha o linter do Redocly ou use Spectral. Apidog vence quando você quer uma ferramenta para todo o ciclo de vida da API em vez de várias.
O Apidog CLI tem um comando lint? Não. Apidog valida a estrutura quando você importa uma especificação com apidog import, mas não há um apidog lint e nenhuma maneira de criar regras personalizadas no estilo Spectral ou Redocly através do CLI. Para isso, combine Apidog com Spectral.
Posso empacotar um arquivo OpenAPI sem o Redocly CLI? Sim. apidog export --project <id> --format openapi --output ./openapi.json emite um arquivo consolidado e pode visar uma versão específica do OpenAPI com --oas-version. Não é um comando bundle literal, mas cobre a mesma necessidade prática. Se você só quer empacotamento e nada mais, redocly bundle ainda é uma boa escolha focada.
Devo usar o swagger-cli em 2026? Não. O swagger-cli está obsoleto e sem manutenção, e seu próprio repositório aponta o Redocly CLI como o sucessor. Ele apenas validava e empacotava. Use o Redocly CLI para essa tarefa, ou mude para uma plataforma como Apidog se quiser o restante do ciclo de vida também.
Qual a diferença entre isso e a comparação da plataforma de documentação Redocly? Este post é sobre a ferramenta de código aberto @redocly/cli: lintar, empacotar, dividir, juntar e construir documentação. Se você está comparando o produto de documentação Redocly hospedado ou o Redoc como um renderizador de documentação, leia alternativas ao Redocly para documentação de API. Os dois cobrem produtos diferentes que por acaso compartilham um nome. Para a especificação em si, a Especificação OpenAPI é a fonte da verdade, e o Redocly CLI no npm é onde você encontrará os detalhes atuais de instalação.