Apidog CLI vs Redocly CLI: Qual CLI de API usar?

Ambas as ferramentas residem no seu terminal, ambas entendem OpenAPI, e ambas surgem quando uma equipe decide que quer um fluxo de trabalho de linha de comando para suas especificações de API. É aí que a sobreposição termina. Elas resolvem problemas adjacentes de direções opostas, e escolher a errada significa ou lutar contra um linter que não executa testes ou buscar uma plataforma quando tudo o que você queria era uma verificação estrutural rápida.

Esta é uma comparação direta, em nível de comando, entre o CLI do Apidog e o Redocly CLI. Sem argumentos falaciosos. O CLI do Redocly é uma peça de software de código aberto genuinamente boa, e você verá exatamente onde ele se destaca antes que qualquer veredito seja proferido.

Veredito TL;DR

Eles resolvem problemas sobrepostos, mas diferentes.

O Redocly CLI (@redocly/cli, binário redocly) é um especialista em OpenAPI com abordagem "code-first": faz linting com conjuntos de regras personalizadas, agrupa especificações de vários arquivos, os divide e une, e constrói documentações HTML autônomas. É de código aberto, orientado por configuração e nativo do terminal. Se sua especificação é a fonte da verdade e reside no git, esta é a governança que você executa a partir da linha de comando.

O Apidog CLI (apidog-cli, binário apidog) é a interface de linha de comando de uma plataforma de API completa. Ele importa e exporta definições em relação a um projeto e executa cenários de teste de API em CI com relatórios JUnit e HTML. Ele ganha seu lugar quando a mesma especificação também precisa ser simulada (mocked), testada e documentada em um único espaço de trabalho, em vez de ser montada a partir de ferramentas separadas.

Escolha o Redocly CLI quando quiser um linter, bundler e construtor de documentação leve e de código aberto que você executa puramente a partir do terminal. Escolha o Apidog quando preferir ter uma única ferramenta para todo o ciclo de vida da API. Eles também podem trabalhar lado a lado, e a última seção explica como.

Duas filosofias diferentes

O Redocly CLI é centrado em arquivos e "code-first". O documento OpenAPI no disco é o objeto sobre o qual você atua. Cada comando, redocly lint, redocly bundle, redocly build-docs, recebe um caminho para um arquivo e executa sua tarefa localmente, sem necessidade de conta ou servidor. O comportamento é moldado por um arquivo de configuração redocly.yaml que você insere no repositório ao lado da especificação. Esse modelo se encaixa em equipes que tratam a descrição de sua API como código-fonte: revisado em pull requests, controlado em CI, versionado como todo o resto. A OpenAPI Specification é o contrato, e o Redocly CLI é o conjunto de ferramentas que a fiscaliza.

Apidog é centrado em projetos e "platform-first". Você projeta endpoints, constrói servidores mock e cria cenários de teste visualmente no aplicativo desktop ou web, e o CLI é a interface "headless" para um subconjunto desse trabalho. A maioria dos comandos CLI opera contra um projeto Apidog no servidor, identificado por um ID de projeto e autenticado com um token de acesso. A especificação não é um arquivo solto que você verifica no local; ela é importada para um espaço de trabalho ativo onde também pode ser simulada (mocked), testada e publicada como documentação. Um ambiente, muitas tarefas.

Nenhuma das filosofias está errada. Elas se adequam a diferentes equipes. A distinção honesta é esta: Redocly oferece um CLI focado e de código aberto para a governança de especificações, e Apidog oferece um CLI para uma plataforma mais ampla.

Comando por comando

Aqui está a parte que importa, mapeada tarefa por tarefa. Cada comando abaixo é real; nada é inventado.

Algumas dessas linhas merecem uma nota mais explícita, porque a diferença é real e o artigo seria desonesto sem ela.

O linting é o terreno do Redocly, não do Apidog. O Redocly CLI faz lint de OpenAPI, AsyncAPI, Arazzo e Open-RPC contra conjuntos de regras configuráveis, e você pode criar suas próprias regras. O Apidog valida a estrutura de uma definição quando você a importa, mas não há um comando apidog lint, nenhuma configuração no estilo redocly.yaml, e nenhuma maneira de escrever regras personalizadas de guia de estilo através do CLI. Se seu objetivo é um guia de estilo "code-first" aplicado no terminal, o Redocly é a ferramenta. O Apidog não compete aqui, e dizer o contrário seria errado.

Dividir e unir pertencem ao Redocly. O comando redocly split explode uma descrição em uma estrutura de múltiplos arquivos, e redocly join (experimental) mescla vários arquivos em um só. O Apidog não possui nenhum desses comandos. Sua importação resolve $refs de múltiplos arquivos em recursos unificados, e sua exportação emite um único arquivo consolidado, mas isso não é o mesmo que uma utilidade autônoma de divisão/união que você executa em arquivos soltos.

A execução de testes e o mocking pertencem ao Apidog. O Redocly CLI não executa testes de API e não hospeda um servidor mock; isso está fora de seu escopo por design. O Apidog executa cenários de teste em modo "headless" com apidog run e produz relatórios JUnit, HTML, JSON e CLI para seu pipeline, e o mocking é um recurso de primeira classe da plataforma (criado no aplicativo, não via CLI).

Ambos constroem documentação HTML a partir do terminal. O comando redocly build-docs produz um arquivo HTML Redoc autônomo. O comando apidog export --format html escreve um arquivo HTML de documentação a partir do seu projeto. Motores diferentes, mesmo resultado no terminal.

Comandos reais do Redocly CLI

Instale-o globalmente, ou pule a instalação e execute-o via npx:

npm install -g @redocly/cli@latest
# ou, sem instalação global:
npx @redocly/cli@latest lint openapi.yaml

Faça lint de uma especificação. Com um arquivo redocly.yaml presente, isso aplica seu conjunto de regras escolhido (minimal, recommended, recommended-strict, spec, ou regras personalizadas):

redocly lint openapi.yaml

Se você deseja apenas validação estrutural simples, o tipo que o descontinuado swagger-cli costumava fazer, configure o redocly.yaml apenas com a regra spec e execute o mesmo redocly lint. A Redocly publica um guia de migração do swagger-cli porque o Redocly CLI é seu sucessor nomeado. O repositório do swagger-cli agora contém um aviso de descontinuação pelo mesmo motivo; essa ferramenta antiga apenas validava e agrupava, nunca fazia lint com regras de estilo.

Agrupe uma definição de múltiplos arquivos em um único arquivo, seguindo cada $ref:

redocly bundle openapi.yaml --output bundled.json

Se você está vindo do swagger-cli, os flags mapeiam de forma limpa: -o/--outfile se torna --output, -t/--type se torna --ext (json, yaml, ou yml), e -r/--dereference se torna -d/--dereferenced.

Construa documentação HTML autônoma com Redoc:

redocly build-docs openapi.yaml -o docs.html

Divida uma única descrição em um layout de múltiplos arquivos, o inverso do agrupamento:

redocly split openapi.yaml --outDir ./split-spec

Para uma visão mais ampla de como o Redocly se compara a outras ferramentas nesta categoria, o guia de configuração de linter OpenAPI abrange Spectral, Redocly e Vacuum lado a lado, e o resumo de alternativas ao Redocly cobre especificamente a plataforma de documentação.

Comandos reais do Apidog CLI

Instale o CLI e autentique com um token do aplicativo (avatar, depois Configurações da Conta, depois Token de Acesso à API):

npm install -g apidog-cli@latest
apidog login --with-token <TOKEN>

O token é salvo em ~/.apidog/config.toml. Não o imprima nem o commite.

Importe uma definição para um projeto. Isso valida a estrutura e a ingere, resolvendo $refs de múltiplos arquivos em recursos unificados:

apidog import --project 123456 --format openapi --file ./openapi.json

A importação aceita mais do que OpenAPI: Postman, HAR, Insomnia, JMeter, WSDL, YApi, RAP2, apiDoc, Hoppscotch, Markdown, JSON Schema e o formato próprio do Apidog.

Exporte um único arquivo consolidado, opcionalmente atualizando a versão OpenAPI. Isso é o agrupamento mais uma atualização de versão opcional em uma única etapa:

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Exporte documentação HTML diretamente do projeto:

apidog export --project 123456 --format html --output ./docs.html

Execute um cenário de teste em CI e emita relatórios que seu pipeline pode ler:

apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

Você também pode executar totalmente offline a partir de um arquivo de coleção exportado, sem necessidade de projeto ou token:

apidog run ./collection.apidog-cli.json

A referência completa dos flags, incluindo --out-dir, -n/--iteration-count, -d/--iteration-data e --env-var, está no guia completo do Apidog CLI. A documentação oficial do Apidog CLI aborda a instalação e cada comando de recurso. Para uma comparação de executores de CI, veja Apidog CLI vs Newman e Bruno CLI vs Apidog CLI.

Quando escolher o Redocly CLI

Opte pelo Redocly CLI quando a especificação for sua fonte da verdade e você quiser governá-la como código.

Você quer um linter real com regras personalizadas. O comando lint do Redocly e sua configuração redocly.yaml são o recurso principal: escolha um conjunto de regras embutido ou escreva o seu próprio, e imponha convenções de nomenclatura, campos obrigatórios e estilo da casa em cada commit. Nada no CLI do Apidog se compara a isso. Se a governança de estilo nativa do terminal é o objetivo, o Redocly é a resposta.

Você quer código aberto sem conta. O CLI roda inteiramente em sua máquina ou no executor de CI. Sem login, sem token, sem chamadas de servidor para lint, bundle, split ou build-docs. Para ambientes isolados (air-gapped) ou regras estritas de manipulação de dados, isso é um requisito rigoroso que o Redocly atende e um CLI de plataforma geralmente não.

Você quer um conjunto de ferramentas leve e focado. Se tudo o que você precisa é lint, bundle, split, join e documentação HTML a partir do terminal, o Redocly faz exatamente isso e nada mais. Você pode instalá-lo ou executá-lo via npx com configuração zero. O conjunto completo de comandos está na documentação do Redocly CLI e na página do pacote npm.

Quando escolher o Apidog

Opte pelo Apidog quando a especificação for uma parte de um ciclo de vida maior que você preferiria não montar a partir de ferramentas separadas.

Você quer design, mock, teste e documentação em um só lugar. O CLI importa sua especificação, exporta um arquivo consolidado limpo na versão OpenAPI que você escolher e executa cenários de teste em CI. O mesmo projeto também oferece design visual, um servidor mock e documentação publicada, todos compartilhando uma única definição. Você para de conectar um linter, uma ferramenta de mock, um executor de testes e um gerador de documentação.

Você quer execução de testes em seu pipeline com relatórios utilizáveis. O comando apidog run produz XML JUnit para seu dashboard de CI, além de artefatos HTML e JSON, e sai com código diferente de zero quando um teste falha. O Redocly não executa testes, então se a validação de testes em CI está em sua lista, é aqui que o Apidog se encaixa. Os padrões em validação OpenAPI em CI se combinam naturalmente com uma execução de teste no mesmo pipeline.

Você quer uma única fonte da verdade para toda a equipe. Os recursos residem em um projeto Apidog onde designers, testadores e redatores trabalham. O CLI é a superfície de automação sobre esse espaço de trabalho compartilhado, o que é adequado para equipes que preferem colaborar em uma plataforma a passar arquivos de especificação uns para os outros.

Baixe o Apidog para acompanhar. É gratuito para começar, sem necessidade de cartão de crédito.

Eles podem ser complementares

Não é estritamente uma escolha entre um ou outro, e fingir que é perderia a configuração mais prática.

Um fluxo de trabalho robusto executa o Redocly CLI (ou Spectral) como o gate de lint em CI, aplicando seu guia de estilo em cada pull request, e usa o Apidog para design, mocking, execução de testes e documentação publicada. Faça lint onde o lint é melhor, com conjuntos de regras de código aberto no terminal. Faça mock, teste e documente onde uma plataforma é melhor. A especificação flui entre eles: faça lint do arquivo em CI, importe-o para o Apidog para tudo o que vier a seguir.

Essa combinação explora a força real de cada ferramenta, em vez de forçar uma a fazer o trabalho da outra.

FAQ

O Apidog CLI possui um comando de lint com regras personalizadas como o Redocly?

Não. O Apidog valida a estrutura de uma definição quando você a importa, mas não há um comando apidog lint e nenhuma maneira de criar regras personalizadas de guia de estilo através do CLI. Para linting configurável e "code-first", use o Redocly CLI ou o Spectral.

O Redocly CLI pode executar testes de API em CI?

Não. O Redocly CLI faz lint, agrupa, divide, une e constrói documentação. Ele não executa testes de API e não hospeda um servidor mock. Para execuções de teste "headless" com relatórios JUnit e HTML, use apidog run.

O Apidog é de código aberto como o Redocly CLI?

Não. Redocly CLI e Spectral são de código aberto. O Apidog é freemium: o CLI é gratuito para instalar via npm, mas opera contra uma conta e projeto Apidog, em vez de ser um software totalmente de código aberto.

Eu usava o swagger-cli para validação e agrupamento. Para o que devo migrar?

Ambas as ferramentas cobrem isso. O Redocly CLI é o sucessor nomeado do swagger-cli, com redocly lint (configure a regra spec para validação simples) e redocly bundle. O Apidog abrange o mesmo terreno através de apidog import (validar) e apidog export (agrupar, com um aumento opcional da versão OpenAPI), e adiciona mocking, testes e documentação no mesmo espaço de trabalho.