Abrió una solicitud de extracción, la documentación se generó correctamente, y tres días después un compañero de equipo le envía un mensaje: el servidor de staging rechaza cada solicitud porque el archivo OpenAPI tiene una referencia `$ref` colgante que apunta a una ruta que usted renombró. La especificación parecía correcta en el editor. Se renderizaba en Swagger UI. Simplemente no era realmente válida, y nada en su pipeline lo detectó antes de que se publicara.
Ese es exactamente el trabajo para el que está construida una herramienta de línea de comandos de Swagger: detectar especificaciones defectuosas antes de que lo haga un humano. La frase "swagger cli" generalmente se refiere a `@apidevtools/swagger-cli`, un pequeño paquete npm cuyas dos comandos, `validate` y `bundle`, verifican un documento OpenAPI y unen especificaciones de múltiples archivos en uno solo. Es una herramienta genuinamente útil, y esta guía le muestra cómo usarla correctamente. También muestra dónde se detiene, porque validar una especificación es solo la primera mitad de confiar en una API; la segunda mitad es enviar solicitudes reales y afirmar lo que regresa, y ahí es donde un ejecutor como la CLI de Apidog toma el relevo.
Así que esto es realmente un trabajo que requiere dos terminales. Primero, analice y empaquete la especificación con `swagger-cli` (o su sucesor) para que el contrato sea sólido. Luego, ejecute pruebas reales contra la API en funcionamiento desde la línea de comandos para saber que la implementación coincide con el contrato. Cubriremos ambos, seremos honestos sobre qué herramienta se encarga de cada tarea y le daremos comandos para copiar y pegar para cada uno.
A qué se refiere realmente "swagger cli"
No existe un único binario oficial llamado "swagger". El nombre se refiere a varias herramientas diferentes, y saber a cuál se refiere evita mucha confusión.
@apidevtools/swagger-clies el paquete al que se refiere la mayoría de la gente. Su binario es `swagger-cli`, y hace dos cosas: validar un documento OpenAPI o Swagger 2.0, y empaquetar una especificación de múltiples archivos en un solo archivo. Es el foco de la primera mitad de este artículo.swagger-codegenes un proyecto separado y mucho más grande de SmartBear que genera SDKs de cliente y stubs de servidor a partir de una especificación. Es un trabajo completamente diferente; lo mencionaremos al final.- Swagger UI y Swagger Editor no son CLIs en absoluto. Renderizan y editan especificaciones en un navegador. Si aún está aprendiendo el formato, la introducción a Swagger y OpenAPI es el punto de partida correcto.
Esta guía trata sobre el trabajo de línea de comandos: validar, empaquetar, linting y luego probar. Si desea una visión más amplia de las plataformas de diseño y prueba, el resumen de alternativas de Swagger cubre el lado de la interfaz gráfica de usuario.
Instalación de swagger-cli
La herramienta se distribuye como un paquete npm. Instálelo globalmente:
npm install -g @apidevtools/swagger-cli
Confirme que se resolvió:
swagger-cli --version
swagger-cli --help
Node.js es la única dependencia del sistema. Cualquier máquina o imagen CI con Node ya instalado puede ejecutarlo. Si prefiere no instalarlo globalmente, puede llamarlo bajo demanda con `npx @apidevtools/swagger-cli ...`, lo cual es útil en ejecutores de compilación efímeros.
Una cosa que debe saber antes de depender de él: los mantenedores han marcado `swagger-cli` como obsoleto. El README lo dice claramente, citando la carga de mantenimiento de una gran base de usuarios con pocos colaboradores. Todavía funciona, y muchos pipelines lo ejecutan hoy, pero los nuevos proyectos se dirigen a Redocly CLI como el sucesor mantenido activamente. Cubrimos esa migración en su propia sección a continuación, para que pueda decidir con los ojos bien abiertos.
Validando una especificación con swagger-cli
El comando principal es `validate`. Apúntelo a su archivo de especificación:
swagger-cli validate openapi.yaml
Si el documento es correcto, obtendrá una confirmación de una línea y un código de salida de `0`. Si algo está mal, obtendrá un error que describe el problema y un código de salida distinto de cero, que es exactamente lo que desea en un pipeline.
`validate` ejecuta dos comprobaciones internamente, y puede desactivar cualquiera de ellas:
swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml
`--no-schema` omite la validación contra el esquema JSON de OpenAPI, la comprobación estructural que confirma que su documento tiene la forma correcta. `--no-spec` omite la validación contra las reglas de la especificación en sí, la comprobación semántica que detecta cosas como IDs de operación duplicados o un `$ref` que no apunta a ninguna parte. La mayor parte del tiempo querrá ambas activadas, que es el valor predeterminado. Las banderas existen para el raro caso en que una capa está señalando algo que usted tiene una razón deliberada para permitir.
Lo que `validate` detecta bien: YAML mal formado, campos obligatorios faltantes, punteros `$ref` rotos y errores estructurales que hacen que una especificación sea imposible de analizar. Lo que no hace es hacer cumplir el estilo de su equipo. Pasará felizmente una especificación sin descripciones, nombres inconsistentes y sin ejemplos, porque ninguna de esas reglas rompe las reglas de OpenAPI. Para ese tipo de comprobación con opinión, necesita un linter, que es la siguiente sección.
Si la validación es lo único que buscaba, la guía más detallada sobre cómo validar especificaciones OpenAPI compara varias herramientas y casos extremos que vale la pena conocer.
Empaquetando una especificación de múltiples archivos
Las especificaciones reales rara vez viven en un solo archivo. Se dividen los esquemas en un directorio `components/`, se referencian con `$ref`, y se mantiene el archivo raíz legible. Esto es una buena práctica de higiene, pero muchas herramientas posteriores desean un único documento autocontenido. El comando `bundle` aplana el árbol:
swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml
Las banderas que vale la pena conocer:
-o, --outfile <file>escribe el resultado en un archivo en lugar de imprimirlo en la salida estándar.-t, --type <json|yaml>establece el formato de salida. Por defecto es `json`, así que pase `-t yaml` si desea una salida YAML.-r, --dereferenceincrusta completamente cada `$ref` en lugar de solo recopilar archivos externos en un solo documento. Esto produce un archivo más grande sin referencias restantes, lo que algunos consumidores requieren.-f, --format <spaces>controla la indentación, con un valor predeterminado de 2 espacios.-w, --wrap <column>establece la longitud de línea para el ajuste de líneas de cadenas YAML largas.
La distinción entre un paquete simple y `--dereference` es importante. Un paquete normal mantiene los punteros `$ref` internos, pero reúne todos los archivos separados en uno solo, de modo que el documento es portátil. `--dereference` resuelve cada referencia en objetos en línea, lo que aumenta el tamaño del archivo pero garantiza que ningún consumidor tenga que resolver un puntero. Use el paquete simple para la distribución y la forma desreferenciada solo cuando una herramienta específica lo exija.
Un patrón común es validar y empaquetar en un solo paso como parte de una compilación:
swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json
El `&&` significa que el paquete solo se ejecuta si la validación es exitosa, por lo que una especificación rota nunca produce un artefacto de compilación.
Conectando swagger-cli a CI
La validación es más valiosa cuando se ejecuta en cada cambio, no cuando alguien se acuerda. Insértela en su pipeline como una puerta rápida. Aquí hay un paso de GitHub Actions que falla la compilación en una especificación no válida:
name: Validate OpenAPI spec
on:
pull_request:
paths:
- 'openapi.yaml'
- 'components/**'
jobs:
validate-spec:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Validate spec
run: npx @apidevtools/swagger-cli validate openapi.yaml
Dado que `swagger-cli validate` sale con un código distinto de cero si la especificación es incorrecta, el paso se vuelve rojo y la solicitud de extracción muestra una comprobación fallida. No se necesita configuración adicional. El filtro `paths` evita que la tarea se ejecute cuando la especificación no ha cambiado, lo que reduce sus minutos de CI.
Esta es la puerta de calidad más barata que puede agregar a un repositorio de API. Cuesta segundos y detiene una clase completa de errores de "la documentación mintió" antes de que lleguen a cualquier usuario final.
Cuando necesita linting, no solo validación
La validación responde a una pregunta: ¿es este un documento OpenAPI legal? El linting responde a una pregunta más difícil: ¿es este un buen documento OpenAPI según los estándares de nuestro equipo? Esas no son lo mismo, y `swagger-cli` solo hace lo primero.
Supongamos que su guía de estilo requiere que cada operación tenga un `summary`, cada propiedad tenga una `description` y cada ruta use kebab-case. Una especificación puede violar las tres y aún así pasar `swagger-cli validate`, porque ninguna de esas reglas forma parte de la especificación de OpenAPI. Un linter le permite codificar y hacer cumplir esas reglas.
Esta es la razón principal por la que los equipos se pasan a Redocly CLI, el sucesor mantenido al que el propio `swagger-cli` le indica. Cubre la misma validación y agrupación, y luego añade un motor de linting real.
Migrando a Redocly CLI
La migración es pequeña porque los nombres de los comandos son similares. Instale el sucesor:
npm install -g @redocly/cli
El equivalente a validar es `lint`. Para que coincida estrechamente con el comportamiento antiguo, extienda el conjunto de reglas mínimas:
redocly lint --extends=minimal openapi.yaml
Ejecútelo con el conjunto de reglas predeterminado en su lugar y aplicará un conjunto más estricto de reglas recomendadas, que es donde se muestra el valor del linting. Puede configurar reglas en un archivo `redocly.yaml`, establecer cada una en `error` o `warn`, e incluso escribir complementos personalizados para comprobaciones específicas de la organización.
El empaquetado se mapea casi uno a uno:
redocly bundle openapi.yaml -o dist/openapi.yaml
Los nombres de las banderas cambian ligeramente. `-o/--outfile` de `swagger-cli` se convierte en `--output`, `-t/--type` se convierte en `--ext`, y `-r/--dereference` se convierte en `-d/--dereferenced`. Si sus scripts antiguos usaban las banderas cortas, una búsqueda y reemplazo rápidos lo llevarán allí. Para una comparación más amplia de herramientas de verificación de especificaciones, el desglose de las mejores herramientas de validación de OpenAPI sitúa a Redocly junto a las alternativas.
La versión corta: si está empezando de cero, elija Redocly CLI. Si tiene un paso de `swagger-cli` existente que funciona, no hay prisa, pero el camino a seguir está claro y el cambio de nombre es mecánico.
La mitad que una herramienta de especificación no puede cubrir
Aquí está el límite de todas las herramientas que hemos discutido hasta ahora. `swagger-cli validate` confirma que su especificación está bien formada. `redocly lint` confirma que sigue su estilo. Ninguna de las dos envía una sola solicitud a su API en ejecución. Una especificación puede ser perfecta en papel mientras que la implementación devuelve un 500, omite un campo que prometió o ignora completamente un parámetro de consulta.
Cerrar esa brecha significa realizar pruebas funcionales: enviar una solicitud real a un endpoint real, luego verificar el código de estado, el cuerpo de la respuesta y los valores que contiene. Esa es una categoría de herramienta diferente, y es ahí donde Apidog encaja en el flujo de trabajo.
Apidog es una plataforma API todo en uno. Importa su especificación OpenAPI, y a partir de esa única definición obtiene documentación interactiva, un servidor mock y escenarios de prueba que puede encadenar con aserciones, todo sin salir del espacio de trabajo. La importación es directa; la guía sobre cómo importar Swagger u OpenAPI y generar solicitudes ejecutables lo explica, y puede generar colecciones completas de pruebas directamente desde la especificación en lugar de construirlas manualmente.
La parte que importa para el terminal es el ejecutor de línea de comandos, publicado como el paquete npm `apidog-cli`. Lo instala y ejecuta un escenario guardado sin interfaz gráfica:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
La bandera `-t` es el ID del escenario de prueba, `-e` es el ID del entorno, y `-r` elige formatos de informe como `cli`, `html`, `json` o `junit`. Al igual que `swagger-cli`, sale con un código de estado limpio, por lo que una aserción fallida pone la tubería en rojo. A diferencia de `swagger-cli`, lo que comprueba es el comportamiento en vivo de su API, no solo la forma del archivo que la describe. Para la referencia completa de banderas y ejemplos de CI, consulte la guía completa de Apidog CLI, o ejecute `apidog run --help` para ver las opciones actuales. Si desea configurar ese primer escenario, descargue Apidog, importe su especificación, y el comando del ejecutor es una copia de la pestaña CI/CD del escenario.
Un flujo de trabajo completo de terminal
Una las dos mitades y obtendrá un pipeline que verifica el contrato y la implementación en secuencia:
# 1. ¿La especificación está bien formada y sigue el estilo?
redocly lint --extends=minimal openapi.yaml
# 2. Produzca un único documento distribuible.
redocly bundle openapi.yaml -o dist/openapi.yaml
# 3. ¿La API en ejecución realmente coincide con el contrato?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit
El primer paso falla rápidamente en una especificación mal formada o fuera de estilo. El segundo paso produce el artefacto que consumen sus documentos y generadores de SDK. El tercer paso envía tráfico real y afirma las respuestas, por lo que una compilación exitosa significa que tanto el contrato como el código detrás de él son sólidos. Cada paso sale con un código distinto de cero si falla, por lo que toda la cadena es una única puerta que puede insertar en cualquier ejecutor de CI que tenga Node.
Si su prueba actual se basa en una herramienta de conformidad de especificaciones que se ha silenciado, el artículo sobre la validación de una API contra su especificación sin Dredd cubre la misma idea de contrato versus implementación desde un ángulo diferente.
Una nota sobre swagger-codegen
Las personas que buscan una "swagger cli" a veces en realidad quieren `swagger-codegen`, que es una herramienta diferente con un trabajo diferente. Lee una especificación OpenAPI y genera SDK de cliente, stubs de servidor y documentación en docenas de idiomas. Es genuinamente útil para arrancar un cliente tipado a partir de una especificación publicada, y es justo llamarla la opción de generación de código más capaz de la familia Swagger.
No valida, no hace linting ni prueba en el sentido que cubre este artículo. La generación asume que ya tiene una especificación sólida; si la entrada está rota, la salida estará rota de manera similar. Por lo tanto, incluso en un flujo de trabajo de generación de código, todavía querrá un paso de validación o linting antes. Las herramientas se complementan entre sí en lugar de reemplazarse.