Cómo migrar de Swagger CLI a Apidog CLI

Si aún ejecutas swagger-cli validate y swagger-cli bundle en tu pipeline, estás manteniendo un script alrededor de una herramienta que ya nadie mantiene. El repositorio de GitHub de swagger-cli ahora lo dice directamente: el paquete ya no se mantiene, el README cita la carga de mantenerse al día con una enorme base de usuarios que contribuye poco a cambio, y apunta a los nuevos usuarios a otros lugares.

Así que este es un buen momento para decidir dónde vivirá tu flujo de trabajo de especificaciones a continuación. Esta guía es un manual de migración, no un tutorial de uso. Si no estás listo para migrar y solo quieres seguir usando la herramienta antigua, la guía de Swagger CLI cubre validate y bundle en detalle. Este artículo trata sobre cómo migrar de Swagger CLI a Apidog CLI sin romper tu CI.

Descarga Apidog si quieres seguir los comandos reales. Es gratis para empezar, no se requiere tarjeta de crédito.

Por qué migrar ahora

La respuesta honesta primero: swagger-cli ha sido descontinuado y no se ha mantenido durante un tiempo. Todavía funciona. Muchas pipelines lo utilizan hoy en día. Pero una herramienta que no recibirá correcciones de errores ni actualizaciones de especificaciones es una deuda técnica que reside en tu compilación, y los propios mantenedores recomiendan seguir adelante.

Señalan a un sucesor en particular. Redocly CLI es el reemplazo directo más cercano si todo lo que siempre quisiste fue validar y empaquetar en la terminal. Es de código abierto, "code-first" y nativo de terminal. Su comando lint realiza una validación estructural, y redocly bundle sigue los punteros $ref exactamente como lo hacía swagger-cli bundle. Si tu único objetivo es un intercambio 1:1 que mantenga la especificación como un archivo plano en tu repositorio, Redocly es la elección natural, y Redocly publica su propia guía de migración con el mapeo de comandos. No hay vergüenza en tomar ese camino.

Apidog es para un objetivo diferente. Migra a Apidog CLI cuando quieras que la especificación haga más que simplemente residir en un archivo. En lugar de validar y empaquetar un documento estático, incorporas toda la definición a un espacio de trabajo vivo, luego la validas al importarla, exportas un archivo consolidado cuando lo necesitas y, opcionalmente, simulas la API, ejecutas escenarios de prueba contra ella y publicas documentación desde la misma fuente. swagger-cli solo hacía dos cosas. Apidog cubre el resto del ciclo de vida.

Elige según la adecuación, no la exageración. Si quieres un linter y bundler ligero, configurado por archivo y que ejecutes puramente desde la terminal, Redocly gana. Si prefieres tener una única plataforma para diseño, simulación, pruebas y documentación en lugar de unir varias herramientas, Apidog gana.

Lo que hizo swagger-cli vs lo que hace Apidog CLI

swagger-cli tenía exactamente dos comandos:

• swagger-cli validate <file> comprobaba un documento Swagger 2.0 o OpenAPI 3.0 contra el esquema y verificaba que sus punteros $ref se resolvieran.
• swagger-cli bundle <file> seguía esos punteros $ref y combinaba una definición de múltiples archivos en un solo archivo, con opciones para la ruta de salida (-o), tipo (-t json|yaml), desreferenciación completa (-r) y sangría (-f).

Esa era toda la herramienta. No realizaba linting con reglas de estilo, generaba documentación, ejecutaba pruebas o simulaba nada.

Apidog CLI mapea esas dos tareas en dos de sus comandos, y luego continúa:

• apidog import ingesta una definición en un proyecto de Apidog y la valida al entrar. Las especificaciones de múltiples archivos ven sus punteros $ref resueltos en recursos unificados automáticamente. Este es tu paso de validación, más la ingesta.
• apidog export emite un único archivo consolidado del proyecto, y te permite elegir la versión de OpenAPI al salir. Este es tu paso de empaquetado, más una actualización de versión opcional y la capacidad de emitir documentación HTML o Markdown.
• apidog run ejecuta escenarios y suites de prueba, con JUnit y otros reportes para CI. swagger-cli no tenía un equivalente.
• Los comandos de recursos (endpoint, schema, mock, environment, branch y más) gestionan el proyecto desde la terminal una vez que la especificación está dentro.

Un punto preciso para que el mapeo sea honesto: Apidog valida la estructura al importar, pero no es un linter de guía de estilo configurable. No hay un comando apidog lint ni conjuntos de reglas personalizados. Si dependías de un linting con opiniones, esa parte no se transfiere, y la sección Lo que ganas cubre cómo manejarlo.

Instalar e iniciar sesión

Apidog CLI se distribuye como un paquete npm. Instálalo globalmente:

npm install -g apidog-cli@latest

Luego autentícate con un token de acceso:

apidog login --with-token <TOKEN>

Obtén el token desde la aplicación o web de Apidog: haz clic en tu avatar, ve a Account Settings (Configuración de la cuenta), luego a API Access Token (Token de acceso a la API) y genera uno. La CLI lo almacena en ~/.apidog/config.toml. Trátalo como cualquier otro secreto. No lo imprimas en los registros ni lo subas a tu repositorio.

Si quieres conocer todas las opciones y una explicación más profunda, la guía completa de Apidog CLI y la documentación oficial de Apidog CLI cubren toda la superficie. Para esta migración, la instalación y el inicio de sesión es todo lo que necesitas para empezar.

Tabla de mapeo de comandos

Aquí está la traducción directa de swagger-cli a Apidog CLI. La única diferencia estructural: Apidog trabaja contra un proyecto, por lo que la mayoría de los flujos son de importación y luego exportación en lugar de un solo comando en un archivo suelto.

Las dos celdas más importantes para la migración son las dos primeras filas. Todo lo que está debajo son capacidades que swagger-cli nunca tuvo. La bandera --oas-version es la mejora más clara: swagger-cli podía empaquetar un archivo Swagger 2.0, pero no podía convertirlo en OpenAPI 3.1. Apidog sí puede, al exportar, lo cual es útil cuando estás modernizando un contrato antiguo. Si tu objetivo es la salida de documentación específicamente, exportar OpenAPI a Markdown profundiza en ese formato.

Migración paso a paso

Aquí está el camino completo desde una configuración de swagger-cli hasta un flujo de trabajo de Apidog.

1. Obtén tu ID de proyecto. Crea o abre un proyecto en la aplicación Apidog. El ID del proyecto aparece en la configuración del proyecto y en la URL. Lo pasarás a cada comando CLI mediante --project.

2. Importa la especificación raíz. Apunta Apidog al archivo de entrada de tu definición. Las especificaciones de múltiples archivos con punteros $ref se resuelven automáticamente, así que importas la raíz y Apidog incorpora el resto:

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

Si la especificación está mal formada o un $ref está colgado, la importación falla. Ese fallo es tu puerta de validación, el mismo trabajo que solía hacer swagger-cli validate, ahora incorporado en la ingesta.

3. Verifica en la aplicación. Abre el proyecto y confirma que tus endpoints, esquemas y parámetros se hayan cargado correctamente. Esta verificación visual no tiene un equivalente en swagger-cli, y vale la pena hacerla una vez durante la migración para confirmar que la importación hizo lo que esperabas.

4. Exporta el archivo consolidado. Cuando necesites un único archivo plano (para una herramienta posterior, un generador de clientes o un artefacto), expórtalo. Elige la versión de OpenAPI que desees:

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

Esto reemplaza a swagger-cli bundle. Los punteros $ref ya se resolvieron en la importación, por lo que la exportación es tu salida consolidada de un solo archivo.

5. Intégralo en CI. Reemplaza tu antiguo paso de swagger-cli con la importación (validar al ingerir) y la exportación (empaquetar), y añade una ejecución de pruebas si tienes escenarios. La siguiente sección tiene un ejemplo completo de GitHub Actions.

Ejemplo de CI con GitHub Actions

Este flujo de trabajo instala la CLI, inicia sesión con un token de los secretos del repositorio, importa la especificación para validarla, exporta un artefacto consolidado y luego ejecuta escenarios de prueba con el reportero JUnit para que una prueba fallida haga que la verificación falle y bloquee la PR.

name: API spec check

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Log in
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Import spec (validates on import)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Export consolidated spec
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Run test scenarios
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

Almacena el token como APIDOG_ACCESS_TOKEN en los secretos de tu repositorio para que nunca aparezca en los registros. El reportero -r "cli,junit" escribe un archivo XML de JUnit que tu CI puede mostrar como informe de prueba, y un escenario fallido devuelve un código de salida distinto de cero que bloquea la fusión. Para patrones de pipeline más profundos, consulta la guía de CI/CD de Apidog CLI, y para la configuración específica del ejecutor, la guía Apidog CLI con GitHub Actions.

Lo que ganas más allá de la validación y el empaquetado

Aquí es donde la migración vale la pena, y donde ser honesto es lo más importante.

• Servidores de simulación (Mock servers). Una vez que tu especificación está en un proyecto, Apidog puede servir respuestas simuladas a partir de ella. Puedes desarrollar un frontend contra la API antes de que exista el backend. swagger-cli nunca tocó el comportamiento en tiempo de ejecución.
• Escenarios de prueba automatizados. apidog run ejecuta solicitudes reales contra una API en ejecución y afirma las respuestas. Construyes escenarios visualmente en la aplicación y luego los ejecutas sin interfaz en CI. Eso cierra la brecha que swagger-cli dejó abierta: una especificación válida te dice que el contrato está bien formado, no que la implementación coincida con él.
• Documentación alojada y exportada. apidog export --format html o --format markdown produce documentación directamente desde la misma fuente. No hay un paso de compilación de documentación separado que mantener.

Ahora, el límite honesto. Apidog CLI no tiene un linter de guía de estilo configurable, "code-first" y con conjuntos de reglas personalizados. Valida la estructura al importar, pero no puedes crear reglas al estilo Spectral o Redocly a través de la CLI, y no existe el comando apidog lint. Si tu configuración antigua se basaba en un linting estricto (nomenclatura consistente, descripciones requeridas, ejemplos en cada respuesta), mantén un linter dedicado en el ciclo. Empareja Apidog con Spectral o Redocly para eso, y ejecútalo como un paso separado en CI. La guía de configuración del linter OpenAPI cubre cómo integrarlo. Usar ambos no es una contradicción: haz linting con una herramienta especializada y luego gestiona el ciclo de vida en Apidog.