Si llegaste aquí después de ejecutar npm install -g @apidevtools/swagger-cli y notar las advertencias, aquí está la versión corta: la herramienta ya no se mantiene. El repositorio swagger-cli en GitHub establece claramente que está obsoleto, citando "la carga de mantenimiento de tratar de cumplir con las expectativas de una enorme base de usuarios con poca o ninguna contribución". El propio README te dirige a Redocly CLI como el sucesor.
Así que necesitas un reemplazo. Esto se refiere específicamente a la herramienta de terminal swagger-cli, la que hace validate y bundle. Si en realidad te refieres a Swagger Editor, SwaggerHub o el conjunto de diseño más amplio, lee en su lugar 7 alternativas a Swagger que también prueban tu API.
Veamos qué hacía swagger-cli y luego revisemos la lista honesta de lo que hay que usar ahora.
Qué hacía realmente swagger-cli
Vale la pena ser preciso, porque el reemplazo correcto depende de lo que estuvieras usando.
swagger-cli tenía exactamente dos comandos:
# Valida una definición Swagger 2.0 / OpenAPI 3.0 contra el esquema y comprueba los $refs
swagger-cli validate openapi.yaml
# Sigue los punteros $ref y combina una definición de múltiples archivos en uno solo
swagger-cli bundle openapi.yaml -o bundled.json
El comando bundle tenía un pequeño conjunto de opciones: -o/--outfile para escribir en un archivo, -t/--type para elegir JSON o YAML, -r/--dereference para insertar completamente cada $ref, y -f/--format para la indentación.
Esa era toda la herramienta. Validaba la estructura y agrupaba las especificaciones de varios archivos. No realizaba linting con reglas de estilo, generaba documentación, ejecutaba pruebas ni simulaba nada. Si lees afirmaciones de que swagger-cli "lintaba" tu especificación, están equivocadas; solo comprobaba tu definición contra el esquema OpenAPI y resolvía referencias. Ten en cuenta ese alcance, porque algunos reemplazos hacen mucho más, y puede que lo quieras o no.
La lista corta
Tres herramientas cubren casi todas las razones por las que recurrirías a swagger-cli, además de un par de especialistas que merecen una mención. Aquí está el resumen honesto.
Redocly CLI: el sucesor oficial y el reemplazo 1:1 más cercano
Redocly CLI (@redocly/cli, binario redocly) es de código abierto y es la herramienta a la que te envía el propio README de swagger-cli. Redocly incluso publica una guía de migración desde swagger-cli. Si tu objetivo es un validador y agrupador de terminal listo para usar, empieza aquí.
Instálalo de la misma manera que instalaste swagger-cli:
npm install -g @redocly/cli@latest
# o ejecutar sin instalar
npx @redocly/cli@latest lint openapi.yaml
La correspondencia es clara. validate de swagger-cli se convierte en redocly lint, que comprueba tu especificación y aplica reglas de estilo configurables. bundle de swagger-cli se convierte en redocly bundle:
# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json
Aquí está la correspondencia de banderas de bundle lado a lado:
| swagger-cli | Redocly CLI | Propósito |
|---|---|---|
-o, --outfile |
--output (o -o) |
Escribir en un archivo |
-t, --type |
--ext (json, yaml, yml) |
Formato de salida |
-r, --dereference |
-d, --dereferenced |
Insertar completamente todos los $refs |
Una cosa a tener en cuenta: redocly lint hace más que validate de swagger-cli por defecto. Aplica un conjunto de reglas de guía de estilo, no solo una verificación de esquema. Si quieres la validación estructural simple que te daba swagger-cli, configura un redocly.yaml solo con la regla spec, y luego ejecuta redocly lint openapi.yaml. Ese comportamiento del conjunto de reglas es la fuerza distintiva de Redocly, más que un inconveniente; es por eso que a los equipos que quieren una gobernanza nativa de terminal les gusta. Puedes ajustar los conjuntos de reglas (minimal, recommended, recommended-strict, spec) o escribir reglas personalizadas. Consulta la mejor configuración de linter OpenAPI para ver cómo encaja esto con otros linters.
Redocly CLI también va más allá de los dos comandos de swagger-cli. Puede split una sola descripción en una estructura de múltiples archivos (lo opuesto a bundle), join múltiples archivos (experimental), y construir documentos HTML de Redoc autónomos:
redocly build-docs openapi.yaml -o docs.html
Lo que no hace: ejecutar pruebas de API o alojar un servidor simulado. Es una herramienta de lint/bundle/docs de código primero y nativa de terminal, y una excelente. Si eso es todo lo que necesitas, puedes dejar de leer y migrar hoy.
Apidog: cuando quieres más que validar y empaquetar
Aquí está el replanteamiento honesto. swagger-cli era un script estático que ejecutabas para validar y empaquetar. Pero para la mayoría de los equipos, validar y empaquetar son medios para un fin. Validas para que la especificación sea correcta, empaquetas para que sea portátil, y luego la simulas, la pruebas y la documentas. swagger-cli dejaba esos pasos posteriores a otras herramientas.
Apidog cierra esa brecha. Es una plataforma API todo en uno: diseño, simulación, prueba y documentación en un solo espacio de trabajo, con una CLI que maneja la importación, exportación y la ejecución de pruebas de CI. Donde swagger-cli te daba un archivo, Apidog te da un espacio de trabajo vivo construido a partir de ese archivo.
Los dos comandos que se mapean más directamente a tu memoria muscular de swagger-cli son import y export. Instala la CLI y autentícate primero:
npm install -g apidog-cli@latest
apidog login --with-token <TU_TOKEN>
Obtienes el token de la aplicación o web de Apidog: avatar, luego Configuración de la cuenta, luego Token de acceso a la API. Se almacena en ~/.apidog/config.toml, así que nunca lo imprimas ni lo confirmes en el repositorio.
Importar es tu paso de validación. Ingesta una definición en un proyecto y resuelve los $ref de múltiples archivos en recursos unificados. Si el archivo está mal formado, la importación lo revela:
apidog import --project 123456 --format openapi --file ./openapi.json
La importación acepta una larga lista de formatos más allá de OpenAPI, incluyendo Postman, HAR, Insomnia, WSDL y JSON Schema, lo cual es útil cuando tus fuentes son mixtas.
Exportar es tu paso de agrupación, con un extra. Emite un único archivo consolidado, y tú eliges la versión de OpenAPI en la salida. Esto lo convierte en agrupación más una actualización opcional de la especificación en un solo comando:
# Agrupa y actualiza a OpenAPI 3.1 de una sola vez
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# O emite documentos HTML autónomos
apidog export --project 123456 --format html --output ./docs.html
Para CI, Apidog añade el paso que swagger-cli nunca tuvo: la ejecución de pruebas.
# Ejecuta 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"
# O ejecuta completamente offline desde un archivo de colección exportado
apidog run ./collection.apidog-cli.json
La CLI también gestiona los recursos del proyecto directamente, incluyendo endpoint, schema, mock, environment, branch, test-suite y test-report. Para detalles de configuración y cada bandera, consulta la guía completa de Apidog CLI y la documentación oficial de Apidog CLI.
Ahora, los límites honestos, porque el ajuste es más importante que la exageración. La CLI de Apidog valida la estructura en la importación, pero no te proporciona un linter de guía de estilo configurable, de código primero, con conjuntos de reglas personalizadas como lo hace lint de Redocly. No hay un comando apidog lint, y no puedes crear reglas personalizadas al estilo Spectral a través de la CLI. Tampoco hay split o join. Apidog es GUI-first: el diseño, la simulación, la creación visual de pruebas y la documentación se realizan principalmente en la aplicación de escritorio o web, y la CLI se encarga de la importación, exportación, ejecuciones de pruebas de CI y la gestión de recursos de un proyecto. Y Apidog es freemium, no de código abierto, por lo que es un modelo diferente al de Redocly CLI y Spectral.
Spectral: linting puro y personalizable en CI
Si lo que realmente buscabas de swagger-cli era una validación estricta y con criterio en tu pipeline, el linter dedicado es Spectral de Stoplight. Es de código abierto y está diseñado para una única tarea: aplicar un conjunto de reglas personalizable a documentos OpenAPI (y otros JSON/YAML).
Spectral brilla cuando quieres aplicar un estilo de casa como código, con tus propias reglas, en cada pull request. No agrupa, no genera documentación y no prueba endpoints; hace linting. Combínalo con un agrupador y habrás reconstruido una versión enfocada de lo que hacía swagger-cli, además de una gobernanza real. Nuestra guía sobre linting de OpenAPI con Spectral te muestra cómo escribir conjuntos de reglas, y validar OpenAPI en CI cubre cómo integrarlo en un pipeline.
Brevemente: openapi-generator y vacuum
Surgen dos herramientas más, así que aquí está la versión precisa y corta. openapi-generator es un generador de código y clientes; si tu razón para agrupar era alimentar un generador, es posible que no necesites un paso de agrupación separado en absoluto, ya que consume especificaciones directamente. vacuum es un linter OpenAPI rápido y compatible con Spectral escrito en Go, una buena opción cuando la velocidad de linting en grandes monorepositorios importa. Ninguno es un reemplazo general de validar más agrupar por sí solo, pero ambos satisfacen necesidades específicas.
Tabla comparativa
Aquí se muestra cómo se comparan las opciones en cuanto a las capacidades que suelen importar a los usuarios de swagger-cli.
| Herramienta | Validar | Agrupar | Reglas de Lint | Docs | Mock | Test | Código abierto | Mejor para |
|---|---|---|---|---|---|---|---|---|
| swagger-cli | Sí | Sí | No | No | No | No | Sí (obsoleto) | Nada nuevo; no se mantiene |
| Redocly CLI | Sí (lint) |
Sí | Sí (configurable) | Sí (Redoc HTML) | No | No | Sí | Un reemplazo de terminal para validar/agrupar con gobernanza |
| Apidog | Sí (en importación) | Sí (en exportación, con actualización OAS) | Solo estructural, sin reglas personalizadas | Sí (app + exportación) | Sí | Sí (ejecución CLI) | No (freemium) | Una herramienta para todo el ciclo de vida de la API |
| Spectral | Sí (basado en lint) | No | Sí (reglas personalizadas) | No | No | No | Sí | Linting estricto y personalizable en CI |
| vacuum | Sí (basado en lint) | No | Sí (compatible con Spectral) | No | No | No | Sí | Linting rápido en especificaciones grandes |
La recomendación
Esta no es una situación de "todo es genial, elige tu favorito". Dos caminos claros cubren a casi todo el mundo.
Elige Redocly CLI si quieres un reemplazo directo. Es el sucesor oficial, es de código abierto y la migración es casi mecánica: validate a lint, bundle a bundle, con el mapeo de banderas anterior. Si tu flujo de trabajo es genuinamente solo "validar y agrupar desde el terminal", y te gustaría añadir reglas de gobernanza más adelante sin cambiar de herramientas, Redocly es la elección obvia. Te mantiene centrado en el código y nativo del terminal, que es exactamente donde vivía swagger-cli.
Elige Apidog si validar y agrupar eran solo el principio. La mayoría de los equipos no validan una especificación por sí misma. La validan, luego alguien necesita una simulación para construir sobre ella, alguien más escribe pruebas, y alguien se encarga de la documentación. swagger-cli se detuvo en el primer paso y te obligó a montar el resto con Spectral, un agrupador, Postman y Newman. Apidog reúne la importación (validar), exportación (agrupar más una actualización de la versión OAS), simulación, prueba y documentación en un solo espacio de trabajo, con una CLI para las partes que pertenecen a CI. Dejas de estar pendiente de un script estático, ahora sin mantenimiento, y llevas toda la especificación a un lugar donde sigue siendo útil después de agruparla.
Estos son paradigmas diferentes, no versiones competidoras de la misma cosa. Redocly CLI es el especialista ligero, impulsado por la configuración, que se ejecuta puramente desde la terminal. Apidog es la plataforma todo en uno que resulta tener una CLI capaz. Elige basándote en cuánto del ciclo de vida quieres en una sola herramienta, y sé honesto al respecto: si solo quieres hacer linting y agrupar en la terminal, Redocly es más ligero y gratuito.
Si quieres probar el enfoque del ciclo de vida, descarga Apidog e importa una especificación existente; es gratis para empezar, no se requiere tarjeta de crédito, y podrás ver tu salida agrupada y versionada en unos minutos.
Preguntas frecuentes
¿Se sigue manteniendo swagger-cli?
No. El repositorio de GitHub de swagger-cli está marcado como obsoleto y ya no se mantiene, citando la baja contribución frente a una gran base de usuarios. Todavía se instala y se ejecuta, pero no recibirá correcciones ni actualizaciones, así que planifica una migración.
¿Qué reemplazó a swagger-cli?
El propio README del proyecto apunta a Redocly CLI como el sucesor. redocly lint reemplaza a swagger-cli validate y redocly bundle reemplaza a swagger-cli bundle. Redocly incluso publica una guía de migración dedicada. Si quieres más que validar y agrupar, Apidog cubre la importación, exportación, simulación, prueba y documentación en un solo lugar.
¿Es Apidog gratuito?
Apidog es freemium. Hay un nivel gratuito con el que puedes empezar sin tarjeta de crédito, con planes de pago para equipos más grandes y necesidades avanzadas. No es de código abierto, lo cual es la principal diferencia con Redocly CLI y Spectral si las licencias abiertas son un requisito para ti.
¿Puedo mantener mi flujo de trabajo de swagger-cli exactamente como está?
Lo más parecido es Redocly CLI. Para replicar la validación estructural simple de swagger-cli validate, configura un redocly.yaml solo con la regla spec y ejecuta redocly lint. Para la agrupación, los comandos y las banderas se mapean casi uno a uno. Para una mirada más profunda al alcance de la herramienta original, consulta cómo usar swagger-cli desde la terminal.