Validación de OpenAPI con Spectral (Y un método más fácil)

Dos ingenieros del mismo equipo lanzan dos endpoints en la misma semana. Uno devuelve created_at, el otro devuelve createdAt. Uno pagina con ?page=, el otro con ?offset=. Ninguno es incorrecto por sí solo. Juntos, hacen que tu API parezca ensamblada por extraños, y cada cliente que la consume paga el precio. El archivo OpenAPI valida correctamente. Se parsea, se renderiza en Swagger UI, genera un SDK. Simplemente es inconsistente, y un validador simple no tiene nada que decir al respecto.

Esa es la brecha exacta que llena un linter. Un validador responde “¿es esta especificación OpenAPI legal?” Un linter responde “¿sigue esta especificación las reglas que acordamos?” La herramienta de código abierto más popular para la segunda pregunta es Spectral, el linter de Stoplight para documentos JSON y YAML. Viene con un conjunto de reglas OpenAPI incorporado, te permite escribir tus propias reglas y se ejecuta desde la terminal o tu editor. Si quieres una forma gratuita y programable de hacer cumplir una guía de estilo API, Spectral es la primera parada obvia, y esta guía te muestra cómo usarlo correctamente.

También te muestra la compensación. Spectral es un conjunto de reglas que tú mismo ensamblas y mantienes. Para los equipos que prefieren obtener verificaciones de consistencia, servidores mock y pruebas ejecutables desde un solo lugar sin escribir reglas YAML a mano, Apidog integra ese trabajo en la propia superficie de diseño. Primero daremos todo el crédito a Spectral, y luego mostraremos dónde el camino todo en uno te ahorra el mantenimiento.

Qué hace Spectral realmente

Spectral es un linter genérico. Lo apuntas a un documento estructurado, le das un conjunto de reglas y te informa cada lugar donde el documento rompe una regla, con un número de línea y una severidad. No es específico de OpenAPI; entiende OpenAPI, AsyncAPI y Arazzo de forma predeterminada, y puedes lintar cualquier archivo JSON o YAML con reglas personalizadas.

La razón por la que es importante para el trabajo con API es el conjunto de reglas incorporado spectral:oas. Ese conjunto de reglas codifica una larga lista de convenciones de OpenAPI: las operaciones deben tener un operationId, el objeto info debe llevar una descripción y un contacto, las etiquetas deben definirse antes de usarse, los parámetros no deben duplicarse entre sí. Ejecútalo contra una especificación del mundo real y casi siempre obtendrás una lista de advertencias en el primer intento. Ninguna de ellas rompe un parser. Todas ellas hacen que la especificación sea más difícil de manejar.

Este es un trabajo diferente de la validación estructural. Una herramienta como swagger-cli o Redocly responde si el documento se ajusta al esquema OpenAPI. Spectral responde si el documento sigue tu estilo de casa además de eso. Quieres ambas cosas, y las dos comprobaciones se componen limpiamente en un pipeline. Recorremos la mitad de la validación en la guía sobre cómo validar especificaciones OpenAPI; este artículo trata sobre la mitad de estilo y consistencia.

Instalación de Spectral y ejecución de tu primer lint

Spectral se distribuye como un paquete npm. La CLI es @stoplight/spectral-cli. Instálala globalmente:

npm install -g @stoplight/spectral-cli

Node.js es la única dependencia del sistema, por lo que cualquier máquina o imagen CI con Node ya instalado puede ejecutarlo. Si prefieres no instalarlo globalmente, npx @stoplight/spectral-cli ... funciona en ejecutores de compilación efímeros.

Spectral necesita un conjunto de reglas para saber qué comprobar. La convención es un archivo llamado .spectral.yaml en tu directorio de trabajo. El más pequeño útil extiende las reglas OpenAPI incorporadas:

# .spectral.yaml
extends: ["spectral:oas"]

Ahora, lintea una especificación. Con un .spectral.yaml en el directorio actual, Spectral lo detecta automáticamente:

spectral lint openapi.yaml

O apunta explícitamente a un conjunto de reglas:

spectral lint openapi.yaml --ruleset .spectral.yaml

El resultado es legible a propósito. Cada hallazgo muestra la línea y la columna, la severidad, la regla que se activó y un mensaje humano:

openapi.yaml
  3:6   warning  info-contact      Info object should contain `contact` object.
  5:10  error    info-description   OpenAPI object info `description` must be present.

✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)

Esa primera ejecución contra una especificación existente es el momento en que la mayoría de los equipos se dan cuenta de cuánto desfase se ha infiltrado. Las reglas nunca se aplicaron, así que nadie las siguió.

Escribiendo tus propias reglas

El conjunto de reglas integrado es un punto de partida, no el destino. El valor real de Spectral es codificar las convenciones de tu equipo como reglas que una máquina verifica en cada cambio. Una regla tiene cuatro partes móviles: qué buscar (given, una expresión JSONPath), qué verificar (then, una función), cuán estricto ser (severity) y qué decir cuando falla (message).

Aquí tienes una regla que impone el kebab-case en las rutas, una convención común en casa:

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Las rutas deben estar en kebab-case.
    message: "{{property}} debe estar en kebab-case (minúsculas, separadas por guiones)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"

El given selecciona cada clave de ruta. El then ejecuta la función pattern incorporada contra una expresión regular. Cualquier cosa que falle el patrón se reporta como una advertencia con tu mensaje. Puedes prohibir los IDs enteros en favor de los UUID, requerir una respuesta de error en cada POST, prohibir los números de versión en las URL de los servidores, o requerir que cada operación lleve una descripción. Spectral incluye varias funciones principales (truthy, pattern, schema, length, enumeration, y más) por lo que la mayoría de las convenciones no necesitan ningún código.

Cuando una regla necesita una lógica que una opción de función no puede expresar, Spectral te permite escribir reglas en JavaScript o TypeScript e importar funciones personalizadas. Ahí es donde la herramienta se vuelve potente y donde comienza el mantenimiento. Si quieres profundizar tanto, tenemos un tutorial completo sobre cómo construir reglas personalizadas de Spectral con TypeScript.

Severidad y cómo hacer que la compilación falle

Cada regla de Spectral tiene una severidad: error, warn, info o hint. Por defecto, la CLI solo sale con un código distinto de cero cuando encuentra un error. Las advertencias se imprimen pero no hacen que la ejecución falle. Eso está bien mientras estás limpiando una especificación heredada y no quieres que mil advertencias bloqueen cada fusión.

Una vez que tu especificación esté limpia, ajusta la puerta. El flag --fail-severity controla el umbral:

spectral lint openapi.yaml --fail-severity=warn

Ahora una advertencia también devuelve el código de salida 1, que es lo que un paso de CI lee para marcarse como fallido. Este es el mecanismo que convierte un linter en una verdadera puerta de calidad: el pipeline bloquea la fusión en el momento en que la especificación se desvía de la guía de estilo. También puedes anular las severidades de las reglas individuales en tu conjunto de reglas, elevando una regla que te importa de warn a error o silenciando una que no se ajusta a tu equipo configurándola en off.

Ejecutando Spectral en CI

Un linter que solo se ejecuta cuando alguien se acuerda no es una puerta. El objetivo es ejecutarlo en cada push, en una máquina limpia, con el mismo conjunto de reglas para todos. Spectral hace esto corto. Aquí hay un trabajo de GitHub Actions que lintea la especificación en cualquier pull request que la toque:

name: Lint OpenAPI

on:
  pull_request:
    paths:
      - "openapi.yaml"

jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install -g @stoplight/spectral-cli
      - run: spectral lint openapi.yaml --fail-severity=warn

Para informes más completos, Spectral puede emitir XML de JUnit, que la mayoría de los paneles de CI parsean en un árbol de aprobado/fallido:

spectral lint openapi.yaml -f junit -o results.xml

Conecta ese artefacto a tu panel de control y cada colaborador verá qué regla falló y dónde, sin tener que leer registros sin procesar. Si quieres una visión más amplia de la superposición de comprobaciones estructurales, linting y detección de cambios importantes, los patrones OpenAPI-en-CI se generalizan más allá de cualquier herramienta individual. Tratar la especificación como código es la mentalidad que hace que todo esto funcione.

Donde Spectral te exige mucho

Spectral es bueno en lo que hace. El inconveniente honesto es que hace una cosa, y el resto del ciclo de vida de la especificación es tu problema para unificarlo. Algunas realidades aparecen una vez que un equipo lo adopta más allá de la demostración.

Eres el propietario del conjunto de reglas. Las reglas integradas de spectral:oas son genéricas. Tu guía de estilo real reside en las reglas personalizadas que escribes, revisas, versionas y mantienes actualizadas a medida que evolucionan las convenciones. Ese conjunto de reglas se convierte en una pequeña base de código con su propia carga de mantenimiento, y JSONPath más las funciones personalizadas es una habilidad que no todos en el equipo poseen.

Lintea el documento, no la API. Spectral lee el archivo. No puede decirte si el servicio en ejecución realmente devuelve lo que promete la especificación. Una especificación puede pasar todas las reglas de lint y aun así describir un endpoint del que la implementación se desvió hace meses. Cerrar esa brecha significa enviar solicitudes reales y verificar las respuestas, lo cual es una herramienta completamente diferente.

Es una pieza de una cadena más larga. Después de linting, todavía necesitas mocks para los equipos frontend, un sitio de documentación y un conjunto de pruebas automatizadas. Cada uno es una herramienta separada para instalar, configurar y mantener sincronizada con la especificación. El linter no conoce ninguna de ellas, por lo que la especificación se vuelve a parsear y reinterpretar en cada etapa.

Nada de esto es una crítica a Spectral. Es un linter enfocado y es honesto sobre su alcance. Pero “enfocado” significa que el trabajo de integración recae en ti.

La forma más fácil: consistencia integrada en la superficie de diseño

Aquí está el otro camino. En lugar de tratar la consistencia como un paso de lint que se añade después de que se escribe la especificación, Apidog la trata como parte de la escritura de la especificación.

Apidog es una plataforma API todo en uno: diseñas el esquema, depuras solicitudes, creas escenarios de prueba, simulas endpoints y publicas documentos en un solo espacio de trabajo. Debido a que el diseño ocurre dentro de la herramienta, las verificaciones de consistencia suceden mientras escribes. El diseñador visual detecta problemas estructurales en el momento en que aparecen, de la misma manera que un compilador subraya un error de sintaxis, para que los corrijas antes de que lleguen a un commit. No estás ejecutando un linter por separado después del hecho; el editor es el linter.

La mayor diferencia es todo lo que viene después. El mismo contrato que diseñas se convierte en tu servidor de simulación, tus documentos interactivos y tus escenarios de prueba, sin volver a parsear y sin una segunda herramienta que mantener sincronizada. Cuando deseas esas comprobaciones en un pipeline, la CLI de Apidog ejecuta tus escenarios de prueba sin interfaz desde la terminal y sale con un código distinto de cero si falla, exactamente el comportamiento de puerta que deseabas de un linter, excepto que prueba la API en ejecución contra el contrato en lugar de solo leer el archivo. Instálala con un comando npm y apúntala a un escenario:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -r cli

Eso llena el vacío que Spectral deja abierto. Spectral confirma que el documento sigue tu estilo. La CLI de Apidog confirma que la implementación aún coincide con el documento. Para la referencia completa de los flags, ejecuta apidog run --help o lee la guía completa de la CLI.

Así que el intercambio es real y vale la pena decirlo claramente. Spectral te ofrece un linter gratuito, programable y neutral respecto al proveedor, que tú mismo ensamblas y mantienes. Apidog te ofrece consistencia, mocking, documentación y pruebas ejecutables desde una única fuente de verdad, con mucho menos que conectar. Si un paso de linting portátil en una cadena de herramientas existente es todo lo que necesitas, Spectral es una buena respuesta. Si quieres que todo el ciclo de vida se mantenga sin convertirse en un proyecto de herramientas propio, la ruta integrada te costará menos con el tiempo.

Spectral vs Apidog de un vistazo

Usa la tabla como ayuda para la decisión, no como un marcador. La elección correcta es la que coincide con la cantidad de ciclo de vida que quieres que una herramienta posea.

Preguntas frecuentes

¿Spectral es gratis? Sí. Spectral es de código abierto bajo la licencia Apache 2.0, mantenido por Stoplight. La CLI, el conjunto de reglas OpenAPI incorporado y la creación de reglas personalizadas son todos de uso gratuito.

¿Spectral valida que mi especificación sea un OpenAPI legal? Parcialmente. Las reglas incorporadas detectan muchos problemas estructurales, pero Spectral es un linter, no un validador de esquema dedicado. Combínalo con un validador para una cobertura estructural completa. La guía sobre validar especificaciones OpenAPI cubre ese aspecto, y las mejores herramientas de validación de OpenAPI compara las opciones.

¿Puede Spectral probar mi API en ejecución? No. Spectral solo lee el archivo de especificación. Para verificar que la API en vivo coincide con el contrato, necesitas un ejecutor que envíe solicitudes reales y valide las respuestas, como la CLI de Apidog.

¿Cómo hago que una advertencia de Spectral falle mi compilación de CI? Ejecuta spectral lint openapi.yaml --fail-severity=warn. Por defecto, solo la severidad error falla la compilación; --fail-severity=warn hace que las advertencias también devuelvan un código de salida distinto de cero.

¿Cuál es la diferencia entre Spectral y Apidog? Spectral es un linter de código abierto enfocado que tú configuras y mantienes. Apidog es una plataforma todo en uno donde el diseño, las comprobaciones de consistencia, el mocking, la documentación y las pruebas conviven, de modo que ensamblas menos y mantienes menos cosas sincronizadas. Consulta Apidog vs Swagger para una comparación relacionada del panorama de las herramientas de diseño.

Conclusión

Spectral resuelve un problema real que los validadores simples ignoran: mantener una especificación OpenAPI consistente con las convenciones acordadas por tu equipo. Instala @stoplight/spectral-cli, extiende spectral:oas, añade algunas reglas personalizadas y protege tu pipeline con --fail-severity=warn. Para muchos equipos, eso es suficiente y no cuesta nada.

El costo aparece más tarde, en las reglas que mantienes y el resto del ciclo de vida que construyes alrededor del linter. Si prefieres obtener consistencia, mocks, documentación y pruebas ejecutables desde una única fuente de verdad, descarga Apidog y construye tu especificación donde las comprobaciones ya son parte de la superficie. De cualquier manera, el objetivo es el mismo: una especificación en la que todo tu equipo pueda confiar, aplicada por una máquina en lugar de una esperanza.