Un archivo Swagger roto rara vez se anuncia. El YAML se analiza correctamente. La página de documentación se renderiza. Luego, un desarrollador frontend genera un cliente a partir de su especificación, la compilación falla por un campo `required` faltante, y descubre que la descripción de su API "terminada" tenía un error tipográfico en un `$ref` tres confirmaciones atrás. La especificación estuvo mal todo el tiempo. Nadie se lo dijo hasta que le costó una tarde a alguien.
Esa es la tarea que realiza un validador de Swagger: lee su archivo OpenAPI o Swagger y le indica, antes de que alguien lo consuma, si el documento es realmente válido. No "si se ve bien", sino "si cumple con la Especificación OpenAPI, resuelve cada referencia y describe un esquema en el que una herramienta puede confiar". Un validador convierte los errores estructurales silenciosos en errores ruidosos, con números de línea que usted corrige en segundos en lugar de depurar aguas abajo durante horas.
Qué comprueba realmente un validador de Swagger
Primero, el nombre. "Swagger" y "OpenAPI" describen lo mismo en diferentes momentos de la historia. El formato se llamó Swagger hasta la versión 2.0, luego fue donado a la Iniciativa OpenAPI y renombrado; 3.0, 3.1 y 3.2 son todos OpenAPI. La gente todavía dice "validador de Swagger" por costumbre, y la mayoría de las herramientas aceptan tanto Swagger 2.0 como OpenAPI 3.x. Si el historial de versiones es confuso, el desglose de Swagger vs OpenAPI lo aclara. Para las diferencias entre las versiones recientes, consulte qué cambió en OpenAPI 3.2 vs 3.1 vs 3.0.
Un validador real realiza tres tareas, en orden:
- Analizar. ¿Es el archivo siquiera un YAML o JSON válido? Una tabulación perdida, una clave duplicada, un corchete sin cerrar, el documento nunca se carga. Este es el error más barato de detectar y el más vergonzoso de enviar.
- Validar estructura. ¿El documento se ajusta al esquema OpenAPI? Cada operación necesita un objeto `responses`. Cada parámetro necesita un valor `in`. Un `$ref` tiene que apuntar a algo que existe. Aquí es donde se esconden la mayoría de los errores reales.
- Resolver referencias. Los documentos OpenAPI están llenos de punteros `$ref` que unen esquemas reutilizables. Un validador sigue cada uno y falla si falta un objetivo, es circular de una manera que la especificación prohíbe, o apunta a un archivo incorrecto.
Si pasa los tres, tendrá un documento que cualquier herramienta compatible, generador de código, servidor de simulacros o renderizador de documentos podrá leer sin problemas. Si falla en cualquiera, el fallo aparecerá en un lugar menos conveniente que su terminal.
Los errores que detecta y que causan problemas más tarde
La validación parece abstracta hasta que se ve lo que se escapa sin ella. Estos son los errores de especificación que parecen inofensivos en el editor y se convierten en incidentes reales en etapas posteriores.
Punteros `$ref` rotos. Usted renombra un esquema de `User` a `UserProfile` pero olvida una referencia en lo profundo de un cuerpo de respuesta. El YAML sigue analizando. Los documentos siguen renderizando el resto de la página. El generador de código encuentra el puntero suelto y emite un cliente con un tipo faltante, o simplemente falla. Un validador marca el `$ref` roto en el momento en que usted guarda.
Desacuerdo entre esquema y ejemplo. Su esquema dice que `age` es un número entero; su ejemplo muestra `"age": "thirty"`. Swagger UI muestra ambos felizmente. Un servidor de simulación construido a partir de la especificación devuelve una cadena donde los consumidores esperan un número, y una prueba de contrato a tres equipos de distancia se pone en rojo por razones que nadie puede rastrear hasta su archivo.
Elementos requeridos faltantes. Una operación sin `responses`. Un parámetro de ruta declarado en la plantilla URL pero nunca definido en `parameters`. Un `requestBody` sin `content`. Cada uno es técnicamente un documento malformado, y cada uno produce un síntoma diferente aguas abajo dependiendo de qué herramienta lea primero la especificación.
Desfase de tipo y formato. `format: date-time` en un campo que su backend devuelve como una marca de tiempo Unix. `type: string` en algo que en realidad es un array. Esto pasa la validación estructural pero rompe el contrato entre la especificación y la API en ejecución, lo cual es un problema aparte al que llegaremos.
El patrón es consistente: un error de especificación es invisible en el momento en que lo comete y costoso en el momento en que alguien más lo consume. La validación traslada el costo de vuelta a donde es barato.
Cómo validar un archivo Swagger manualmente
No necesita una plataforma para empezar. Hay tres formas rápidas de validar una especificación hoy.
El Editor de Swagger. Pegue su YAML en el Editor de Swagger y se validará a medida que escribe, subrayando los errores con números de línea en el margen derecho. Es la forma más rápida de verificar la cordura de un solo archivo, y es gratis. El límite es que es una única caja de texto: valida el documento pero no hace nada sobre si su API real aún coincide con él, y está escribiendo YAML a mano sin un constructor de esquema visual. Para aprender el formato, está bien. Para una especificación de la que depende un equipo, es una pestaña en un flujo de trabajo que necesita varias.
Un linter como Spectral. Spectral de Stoplight es una CLI de código abierto que va más allá de la validez bruta hacia las reglas de estilo. Comprueba la validez estructural y le permite aplicar un conjunto de reglas: cada operación necesita una descripción, cada propiedad de esquema necesita un tipo, la nomenclatura sigue su convención. Spectral es realmente la mejor herramienta de su clase para gobernar el estilo de la especificación en muchos archivos, y si la coherencia en el diseño de la API es su preocupación, vale la pena adoptarla. Se ejecuta así:
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
La contrapartida es el alcance. Spectral valida y revisa el documento. No es un ejecutor de solicitudes; no le dirá si la API que describe la especificación realmente se comporta como la especificación afirma. Esa es una capa diferente, y es la capa donde residen la mayoría de las sorpresas de producción.
Un endpoint de validador en línea. El proyecto Swagger publica un servicio de validador que devuelve una insignia de aprobación o fallo para una URL de especificación alojada. Es útil para una insignia de README, menos para un ciclo de corrección interactivo. Para una cobertura más profunda de las opciones independientes, mantenemos un resumen de las mejores herramientas de validación de OpenAPI y un tutorial enfocado sobre cómo validar especificaciones OpenAPI.
Los tres validan el documento. Ninguno de ellos cierra la brecha entre una especificación válida y una API correcta. Esa brecha es donde vive la siguiente sección.
Dónde encaja Apidog: validar la especificación y luego probar que la API coincide con ella
Apidog es una plataforma API todo en uno: usted diseña el esquema, depura solicitudes, crea escenarios de prueba automatizados, simula endpoints y publica documentos en un solo espacio de trabajo. La validación de especificaciones no es una herramienta separada que se añade; es una propiedad de trabajar en la plataforma.
Cuando importa un archivo Swagger u OpenAPI, o diseña uno en el editor visual, Apidog lo analiza y valida a medida que se ingresa. Un documento malformado, un `$ref` roto, un parámetro sin tipo, estos aparecen a medida que trabaja, no tres herramientas después. Debido a que el editor es visual, toda una categoría de errores de YAML escritos a mano nunca ocurre: no puede olvidar el valor `in` en un parámetro cuando el campo es un menú desplegable requerido. La especificación es válida por construcción.
Eso se encarga del documento. El problema más difícil es la deriva, el lento desacuerdo entre una especificación que dice una cosa y una API que hace otra. Un validador independiente no puede detectar esto, porque el archivo es válido; es el servicio en ejecución el que está mal. Este es el modo de fallo detrás de tantas documentaciones de Swagger y colecciones de Postman que se desvían.
Apidog lo resuelve haciendo de la especificación la fuente de verdad para las pruebas. Usted genera escenarios de prueba directamente desde su especificación OpenAPI, y luego afirma que las respuestas reales coinciden con el esquema que declaró. Cuando la especificación dice que `age` es un entero y la API devuelve una cadena, la prueba falla, y falla contra la especificación, no contra una copia mantenida a mano. La pregunta del validador se convierte en una continua: no "¿era válido este archivo cuando lo guardé?", sino "¿sigue siendo la API en vivo fiel a su contrato en este momento?". Si desea la mecánica de aserción, Afirmaciones de API: una guía práctica cubre la validación de la forma, el estado y los campos de la respuesta.
Para los equipos que desean que la validación se aplique automáticamente en lugar de recordarse, Apidog también cubre mantener las API compatibles con los estándares OpenAPI como parte del ciclo de diseño.
Ejecute la validación basada en especificaciones en CI con la CLI de Apidog
Un validador que solo se ejecuta cuando alguien abre el editor es un validador que eventualmente se omite. La solución es poner la validación en la pipeline, donde se ejecuta en cada push sin intervención humana. Para eso sirve el ejecutor de línea de comandos de Apidog.
La CLI es un paquete npm llamado `apidog-cli`. Ejecuta los escenarios de prueba que construyó en Apidog, de forma desatendida, desde cualquier entorno con Node.js. Instálelo con un solo comando:
npm install -g apidog-cli
Luego, ejecute un escenario guardado, el mismo escenario que afirma que sus respuestas en vivo coinciden con la especificación, contra un entorno:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Algunas notas sobre lo que hacen esas banderas. `-t` es el ID del escenario de prueba. `-e` es el ID del entorno, para que pueda apuntar las mismas comprobaciones al entorno de staging en una pull request y a producción después del despliegue. `-r` elige los formatos de informe: `cli` para una salida de registro de compilación legible, y puede agregar `html`, `json` o `junit` para alimentar un panel de CI. El `--access-token` debe estar en un secreto de CI, nunca en línea. Genere tanto el token como el comando listo para usar desde la pestaña CI/CD del escenario dentro de Apidog. Para la superficie completa de banderas, ejecute `apidog run --help` o lea la guía completa de la CLI de Apidog.
El detalle que hace de esto una verdadera compuerta: la CLI sale con un código de estado distinto de cero cuando una aserción falla. Los sistemas de CI leen ese código de salida. Una verificación de esquema fallida hace que el paso falle, lo que hace que el trabajo falle, lo que bloquea la fusión. Así, en el momento en que su API deja de coincidir con su contrato OpenAPI, la compilación se pone en rojo, antes de que el cambio se envíe, no después de que un consumidor presente un ticket. Esa es la diferencia entre validar un archivo una vez y validar el contrato en cada confirmación. El mismo comportamiento de código de salida es la razón por la que el ejecutor se adapta a cualquier plataforma de CI, al igual que ejecutar colecciones de Postman en CI sin Newman.
Descargue Apidog si desea validación de especificaciones y pruebas de contrato en el mismo lugar donde su equipo ya diseña la API.
Un flujo de trabajo de validación práctico
Uniendo las piezas, aquí hay una secuencia que detecta los errores de especificación en cada etapa, en lugar de solo en la última:
- Diseñe o importe en un editor validador. Ya sea que importe un archivo Swagger existente o lo construya en el diseñador visual de Apidog, el documento se analiza y se valida estructuralmente al ingresar. Las referencias rotas y los tipos faltantes aparecen de inmediato.
- Aplique el linter para el estilo si tiene un conjunto de reglas. Si su organización aplica reglas de nomenclatura y descripción, ejecute Spectral como una verificación rápida antes de la confirmación. La validez y el estilo interno son preocupaciones diferentes; cubra ambas.
- Genere pruebas a partir de la especificación. Convierta el documento OpenAPI en escenarios de prueba para que sus aserciones estén vinculadas a la misma definición que envía, no a una copia separada que se desvía.
- Bloquee cada envío con la CLI. Conecte `apidog run` a su pipeline para que una discrepancia entre la especificación y la realidad falle la compilación automáticamente.
- Trate la especificación como la fuente de verdad. Cuando el diseño cambia, las pruebas apuntan al mismo archivo, por lo que no hay nada que mantener sincronizado manualmente.
Los pasos 1 y 2 validan el documento. Los pasos 3 a 5 validan el contrato. Necesita ambos, y el lugar más económico para hacer todo esto es en un solo espacio de trabajo en lugar de en cuatro pestañas del navegador.
La versión corta
Un validador de Swagger detecta los errores estructurales, las referencias rotas, los tipos faltantes, el YAML malformado, que son invisibles cuando los escribe y costosos cuando alguien más los lee. Validar el documento es el piso, no el techo. Los errores que realmente llegan a producción son aquellos en los que una especificación válida deja de coincidir discretamente con una API cambiante, y ningún validador a nivel de archivo puede verlos.
La solución es validar en dos capas y colocarlas ambas en un solo lugar: valide el documento a medida que lo diseña, luego valide el contrato en cada envío afirmando las respuestas reales contra la especificación. Apidog hace lo primero por construcción y lo segundo a través de escenarios que el ejecutor `apidog-cli` controla en CI. La especificación sigue siendo la fuente de verdad, la compilación se pone en rojo en el momento en que la realidad se desvía de ella, y un archivo Swagger roto deja de ser algo que descubre una tarde demasiado tarde.