Redocly CLI es una buena herramienta. Si la has usado para linting de archivos OpenAPI, para empaquetar una especificación de múltiples archivos en uno solo, o para construir documentos Redoc desde la terminal, ya lo sabes. Entonces, ¿por qué buscar una alternativa a Redocly CLI?
Usualmente se reduce a la forma. Redocly CLI es un especialista enfocado en "código primero": lint, bundle, split, join, construir documentos. Eso es exactamente lo que necesitan algunos equipos y no lo suficiente para otros. Si quieres una herramienta que también diseñe, simule y pruebe tu API, la CLI no intenta ser esa herramienta, y no debería serlo.
Este artículo trata sobre Redocly CLI (el paquete de código abierto @redocly/cli), no sobre el producto de documentos alojados de Redocly. Si estás comparando la plataforma de documentos alojados o Redoc en sí, lee nuestro resumen de alternativas a Redocly para documentación de API en su lugar. Esta publicación es para personas que escriben redocly lint y redocly bundle y quieren saber qué más se adapta a su flujo de trabajo.
Lo que Redocly CLI realmente hace bien
Redocly CLI es de código abierto y nativa de la terminal. La instalas una vez y obtienes un conjunto de comandos concisos que hacen su trabajo de forma limpia. La documentación de Redocly CLI los cubre todos, pero aquí está la versión corta.
El linting es su principal fortaleza. redocly lint valida tu descripción OpenAPI, AsyncAPI, Arazzo u Open-RPC y luego ejecuta reglas de guía de estilo. Configuras todo a través de un archivo redocly.yaml: elige un conjunto de reglas incorporado (minimal, recommended, recommended-strict o spec) o crea tus propias reglas personalizadas. Esa gobernanza impulsada por la configuración es difícil de superar si deseas una aplicación consistente del diseño de API en CI en muchos equipos.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
Bundle, split y join gestionan la plomería de la especificación. redocly bundle sigue los punteros $ref y produce un archivo consolidado. redocly split hace lo inverso, explotando una sola descripción en un diseño de múltiples archivos. redocly join (experimental) fusiona varios archivos OpenAPI en uno.
redocly bundle openapi.yaml --output dist/openapi.json
Los documentos provienen de build-docs. Produce una página HTML Redoc autónoma, y preview-docs te ofrece una vista previa local en vivo.
redocly build-docs openapi.yaml -o docs.html
Así que, si tus necesidades son "validar contra una guía de estilo, empaquetar la especificación y enviar documentos Redoc, todo desde la terminal", Redocly CLI es una opción predeterminada sólida. Muchos equipos deberían conservarla. Las razones para buscar en otro lugar tienen que ver con el alcance, no con la calidad.
Por qué la gente busca una alternativa
Algunos patrones aparecen una y otra vez:
- Quieres una plataforma todo en uno, no solo lint y documentos. Redocly CLI no ejecuta pruebas de API y no aloja un servidor de mock. Si también necesitas diseño, mocking y un ejecutor de pruebas, estás armando una cadena de herramientas a su alrededor.
- Quieres una GUI junto con la CLI. Redocly es "código primero" por diseño. Si tu equipo incluye personas que prefieren trabajar visualmente, la gobernanza solo por terminal es difícil de vender.
- Quieres un ejecutor de pruebas integrado para CI. El linting detecta problemas en la especificación. No te dice si la API en ejecución se comporta correctamente. Para eso se necesita una herramienta separada.
- No quieres unir cinco herramientas. Spectral para linting, Redocly para bundle y documentos, Postman o Newman para pruebas, algo más para mocks. Eso funciona, pero son muchas piezas en movimiento para mantener.
Cada uno de esos puntos apunta a una alternativa diferente. Vamos a emparejarlas.
La lista corta, según lo que realmente querías
Apidog, si quieres una plataforma para todo el ciclo de vida de la API
Apidog es una plataforma de API todo en uno: diseño, mocking, pruebas y documentación en un solo lugar, con una CLI para importar, exportar y ejecutar pruebas de CI. Es la elección correcta cuando prefieres tener una única herramienta para todo el ciclo de vida en lugar de unir un linter, un empaquetador, un ejecutor de pruebas y un servidor de mock.
Aquí la parte honesta. Apidog no tiene un linter de guía de estilo configurable y "código primero" con conjuntos de reglas personalizadas como el lint de Redocly. No hay un comando apidog lint ni una forma de crear reglas personalizadas al estilo Spectral o Redocly a través de la CLI. Apidog valida la estructura cuando importas una especificación, pero si la gobernanza de diseño estricta y personalizable es lo único que te importa, Apidog no reemplazará a redocly lint por sí solo. Combínalo con Spectral para ese trabajo. Volveremos a esto más adelante.
Lo que Apidog te ofrece que Redocly CLI no: un diseñador visual, un servidor de mock incorporado, un constructor de pruebas visual y un ejecutor de pruebas de CI. La CLI maneja las partes que corresponden a la terminal.
# Instalar y autenticar (token de la app: avatar > Configuración de Cuenta > Token de Acceso API)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# Importar una especificación a un proyecto (valida + resuelve $refs de múltiples archivos)
apidog import --project 123456 --format openapi --file ./openapi.json
# Exportar un único archivo consolidado y elegir tu versión OpenAPI
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Ejecutar un escenario de prueba en CI con múltiples formatos de informe
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
apidog import realiza el trabajo de validación al ingerir, y apidog export realiza el trabajo de empaquetado al exportar (emite un solo archivo y puede actualizar la versión OAS). La lista completa de comandos se encuentra en la documentación de Apidog CLI, y nuestra guía completa de Apidog CLI detalla cada bandera. Mejor para: equipos que desean diseño, mocking, pruebas y documentos bajo un mismo techo.
Spectral, si lo único que querías de Redocly era el linter
Si lo único que utilizas es redocly lint, no necesitas cambiar de plataforma. Spectral de Stoplight es el linter de código abierto basado en reglas que se superpone más directamente con el linting de Redocly. Escribes reglas en YAML, las ejecutas contra cualquier documento OpenAPI o AsyncAPI, y lo integras en CI.
El linter de Spectral y Redocly son primos cercanos. Ambos se basan en configuración, ambos vienen con conjuntos de reglas, ambos permiten crear reglas personalizadas. La elección entre ellos a menudo se reduce al ajuste del ecosistema y al formato de conjunto de reglas que tu equipo ya conoce. Nuestro análisis profundo sobre el linting OpenAPI con Spectral cubre la creación de reglas, y la guía más amplia sobre linting de API compara el panorama del linting si quieres la imagen completa. Mejor para: equipos cuya verdadera necesidad es un linting de especificaciones puro y personalizable.
Scalar o Bump.sh, si lo que más querías eran los documentos
Si la parte de Redocly CLI que te importaba era build-docs, la alternativa es una herramienta de documentación, no una plataforma. Scalar y Bump.sh convierten una descripción OpenAPI en documentos de referencia alojados y navegables, cada uno con su propio aspecto y conjunto de características. Se centran en la experiencia de los documentos en lugar de en el linting o las pruebas. Mejor para: equipos cuyo objetivo principal son documentos de referencia de API atractivos y fáciles de mantener.
swagger-cli, que ya no es realmente una opción
Todavía verás swagger-cli mencionado en guías antiguas, así que vale la pena ser claro: swagger-cli está obsoleto. El repositorio de GitHub de swagger-cli dice que ya no se mantiene y señala a Redocly CLI como su sucesor.
Siempre tuvo solo dos comandos, swagger-cli validate y swagger-cli bundle. Nunca hizo linting con reglas de estilo, nunca generó documentos, nunca ejecutó pruebas y nunca simuló nada. Si lo usas hoy, el movimiento es para dejarlo, no para adoptarlo. Nuestra guía sobre cómo usar swagger-cli cubre lo que hacía, e Redocly incluso publica una guía de migración de swagger-cli con el mapeo exacto de las banderas. Incluiremos ese mapeo a continuación para mayor completitud.
Tabla comparativa
Así es como las opciones se comparan con las tareas que maneja Redocly CLI. "Linting de reglas personalizadas" significa un linter de guía de estilo configurable, "código primero" con conjuntos de reglas personalizadas.
| Herramienta | Linting de reglas personalizadas | Empaquetar | Documentos | Mock | Pruebas | GUI | Código abierto | Mejor para |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | Sí | Sí | Sí (Redoc) | No | No | No | Sí | Gobernanza de linting, empaquetado y documentos basada en código desde la terminal |
| Apidog | No | Vía exportación | Sí | Sí | Sí (ejecutor CI) | Sí | No (freemium) | Una plataforma para diseño, mock, pruebas y documentos |
| Spectral | Sí | No | No | No | No | No | Sí | Linting de OpenAPI/AsyncAPI puro y personalizable |
| Scalar / Bump.sh | No | No | Sí | No | No | Sí | Varía | Documentos de referencia de API alojados |
| swagger-cli | No | Sí | No | No | No | No | Sí (obsoleto) | Nada nuevo, no se mantiene |
Una nota sobre la tabla: "Vía exportación" de Apidog significa que apidog export emite un único archivo consolidado, lo que cubre la razón práctica por la que ejecutarías redocly bundle, pero no es un comando bundle idéntico. Y Apidog es freemium, no de código abierto, mientras que Redocly CLI y Spectral son ambos de código abierto. Considera esos intercambios como lo que son.
Mapeo de banderas de bundle de swagger-cli a Redocly CLI
Si estás utilizando el obsoleto swagger-cli y Redocly es tu destino para el empaquetado, las banderas se mapean limpiamente:
| swagger-cli | Redocly CLI | Significado |
|---|---|---|
-o, --outfile <file> |
--output (o -o) |
Escribir en un archivo en lugar de stdout |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
Tipo de archivo de salida |
-r, --dereference |
-d, --dereferenced |
Incrustar completamente todas las $refs |
Así, swagger-cli bundle -o output.json se convierte en redocly bundle --output output.json.
Una recomendación clara
No hay un único ganador, porque la respuesta correcta depende de qué tarea de Redocly CLI estés tratando de reemplazar.
Mantén Redocly CLI si su gobernanza es exactamente lo que necesitas. Un linter, bundler y constructor de documentos Redoc ligero, de código abierto y basado en configuración que se ejecuta puramente desde la terminal es una configuración genuinamente buena. Nada de lo aquí expuesto es una razón para abandonar una herramienta que se ajusta.
Elige Apidog si estás cansado de armar una cadena de herramientas y quieres diseño, mocking, pruebas y documentos en una sola plataforma con una CLI para las partes que se manejan desde la terminal. Dejas de mantener herramientas separadas para cada etapa y obtienes una GUI para las personas de tu equipo que la desean. Solo ten claro que lo combinarás con Spectral si también necesitas linting con reglas personalizadas. La guía de Apidog CLI en CI/CD muestra cómo el ejecutor de pruebas encaja en un pipeline, y Apidog CLI vs Newman lo compara con el ejecutor que muchos equipos ya usan. Puedes descargar Apidog y probarlo gratis, sin necesidad de tarjeta de crédito.
Elige Spectral si el linting es el único propósito. No cambies de plataforma para reemplazar un comando.
El marco honesto: Redocly es un especialista en CLI "código primero", y Apidog es una plataforma visual todo en uno. Son paradigmas diferentes, no un reemplazo directo. Elige según el ajuste.
Preguntas frecuentes
¿Apidog es un reemplazo directo para Redocly CLI? No, y es mejor ser sincero al respecto. Apidog cubre más el ciclo de vida (diseño, mocking, pruebas, documentos) pero no tiene un linter de reglas personalizadas como redocly lint. Si la gobernanza estricta y configurable de la especificación es tu tarea principal, mantén el linter de Redocly o usa Spectral. Apidog gana cuando quieres una sola herramienta para todo el ciclo de vida de la API en lugar de varias.
¿Apidog CLI tiene un comando lint? No. Apidog valida la estructura cuando importas una especificación con apidog import, pero no hay apidog lint ni una forma de crear reglas personalizadas al estilo Spectral o Redocly a través de la CLI. Para eso, combina Apidog con Spectral.
¿Puedo empaquetar un archivo OpenAPI sin Redocly CLI? Sí. apidog export --project <id> --format openapi --output ./openapi.json emite un único archivo consolidado y puede especificar una versión de OpenAPI con --oas-version. No es un comando bundle literal, pero cubre la misma necesidad práctica. Si solo quieres empaquetado y nada más, redocly bundle sigue siendo una opción buena y enfocada.
¿Debería usar swagger-cli en 2026? No. swagger-cli está obsoleto y sin mantenimiento, y su propio repositorio apunta a Redocly CLI como el sucesor. Solo validaba y empaquetaba. Usa Redocly CLI para ese trabajo, o múdate a una plataforma como Apidog si también quieres el resto del ciclo de vida.
¿Cuál es la diferencia entre esto y la comparación de plataformas de documentos de Redocly? Esta publicación trata sobre la herramienta de código abierto @redocly/cli: lint, bundle, split, join y build-docs. Si estás comparando el producto de documentos alojados de Redocly o Redoc como renderizador de documentación, lee alternativas a Redocly para documentación de API en su lugar. Los dos cubren productos diferentes que casualmente comparten un nombre. Para la especificación en sí, la Especificación OpenAPI es la fuente de verdad, y la Redocly CLI en npm es donde encontrarás los detalles de instalación actuales.