¿Cómo se puede usar Spectral para aplicar linting y hacer cumplir los estándares de OpenAPI? #

A medida que los programas de API crecen entre equipos y organizaciones, mantener la coherencia y la calidad de los documentos OpenAPI resulta cada vez más difícil. Los equipos pueden usar convenciones de nomenclatura distintas, omitir campos obligatorios o no seguir las buenas prácticas de seguridad, todo ello sin ninguna red de seguridad automatizada. Spectral, una herramienta de linting de API de código abierto creada por Stoplight, aborda este desafío con un potente y extensible motor de conjuntos de reglas (rulesets) capaz de validar y hacer cumplir estándares en cualquier documento OpenAPI.

¿Qué es Spectral? #

Spectral es una herramienta de línea de comandos y una biblioteca de JavaScript que evalúa documentos JSON y YAML con un conjunto de reglas. Aunque se creó específicamente para OpenAPI, es independiente del formato y puede aplicar linting a cualquier documento estructurado, incluidos los de AsyncAPI, los archivos de configuración YAML personalizados y más.

Sus capacidades principales incluyen:

• Conjunto de reglas de OpenAPI integrado: Spectral incluye conjuntos de reglas con criterio propio para OpenAPI 2.0 y 3.x que abarcan buenas prácticas, corrección estructural y errores comunes.
• Conjuntos de reglas personalizados: los equipos pueden escribir sus propias reglas en JavaScript o usar la sintaxis declarativa de reglas de Spectral para hacer cumplir estándares específicos de la organización.
• Selección mediante JSONPath y JSON Pointer: las reglas apuntan a nodos concretos de un documento mediante expresiones JSONPath.
• Múltiples formatos de salida: los resultados pueden generarse como texto legible, JSON, JUnit XML o SARIF para integrarlos con plataformas de calidad de código.
• Integración con CI/CD: Spectral puede ejecutarse como parte de cualquier pipeline, lo que lo convierte en una barrera de calidad natural para los cambios en las API.

Instalación de Spectral #

Spectral está disponible como paquete de npm y puede instalarse de forma global o como dependencia del proyecto:

npm install -g @stoplight/spectral-cli

Para una instalación limitada al proyecto:

npm install --save-dev @stoplight/spectral-cli

Como alternativa, Spectral puede ejecutarse con Docker:

docker run --rm -it stoplight/spectral lint openapi.yaml

Linting de un documento OpenAPI #

Una vez instalado, aplicar linting a un documento OpenAPI es sencillo:

spectral lint openapi.yaml

Spectral detectará automáticamente si debe aplicar el conjunto de reglas de OpenAPI 2.0 o el de 3.x en función del campo openapi o swagger del documento. Los resultados se muestran en la consola con niveles de gravedad: error, warn, info y hint.

Para aplicar linting con un archivo de conjunto de reglas específico:

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

El conjunto de reglas de OpenAPI integrado #

El conjunto de reglas integrado de Spectral, @stoplight/spectral-openapi, aplica una amplia variedad de reglas de calidad. Algunos ejemplos son:

• operation-operationId: toda operación debe tener un operationId único.
• operation-summary: toda operación debe tener un summary no vacío.
• operation-tags: toda operación debe tener etiquetas para agruparse correctamente en la documentación.
• openapi-tags: las etiquetas usadas en las operaciones deben declararse en el nivel superior.
• info-contact: el objeto info debe incluir un campo contact.
• no-eval-in-markdown: impide las expresiones eval() en los campos de descripción (un problema de seguridad).
• no-script-tags-in-markdown: impide las etiquetas <script> en los campos de descripción.
• path-params: todo parámetro de ruta de una plantilla de URL debe tener su definición de parámetro correspondiente.
• oas3-api-servers: el documento debe definir al menos un servidor.

Estas reglas detectan los errores y omisiones más habituales de los documentos OpenAPI antes de que lleguen a los consumidores o a las herramientas posteriores.

Escritura de un conjunto de reglas personalizado #

Los conjuntos de reglas personalizados permiten a los equipos hacer cumplir estándares de API específicos de la organización. Un archivo de conjunto de reglas de Spectral (.spectral.yaml) tiene la siguiente estructura:

extends: [[spectral:oas, all]]
rules:
  must-have-x-internal-owner:
    description: All operations must declare an internal owner via x-owner
    severity: error
    given: $.paths.*[get,post,put,patch,delete]
    then:
      field: x-owner
      function: truthy

  operation-summary-max-length:
    description: Operation summaries must be 80 characters or fewer
    severity: warn
    given: $.paths.*[get,post,put,patch,delete].summary
    then:
      function: length
      functionOptions:
        max: 80

Cada regla tiene:

• description: una explicación legible de lo que comprueba la regla.
• severity: uno de los valores error, warn, info o hint.
• given: una expresión JSONPath que identifica los nodos que se van a evaluar.
• then: la aserción que se aplica, mediante una función integrada o personalizada.

Funciones integradas #

Spectral proporciona un conjunto de funciones de aserción integradas:

La función casing resulta especialmente útil para hacer cumplir convenciones de nomenclatura en operationId, en los nombres de parámetros y en los nombres de propiedades de esquemas.

Funciones personalizadas #

Para aserciones complejas, Spectral admite funciones personalizadas de JavaScript:

rules:
  path-must-include-api-version:
    description: All paths must start with /v{n}/ to include an API version
    severity: error
    given: $.paths
    then:
      function: checkApiVersion

// .spectral/checkApiVersion.js
export default (paths) => {
  for (const path of Object.keys(paths)) {
    if (!/^\/v\d+\//.test(path)) {
      return [{ message: `Path "${path}" must start with /v{n}/` }];
    }
  }
};

Compartir y extender conjuntos de reglas #

Los conjuntos de reglas de Spectral pueden publicarse en npm y ser extendidos por otros equipos:

extends:
  - spectral:oas
  - "@my-org/spectral-ruleset"
rules:
  # override or add rules here

Esto permite que los equipos de plataforma publiquen un conjunto de reglas central de gobernanza de API como paquete de npm, de modo que cada equipo de API pueda extenderlo con reglas específicas de su proyecto y, al mismo tiempo, heredar la base común de la organización.

Integración de Spectral en pipelines de CI/CD #

Spectral se integra de forma natural en los pipelines de CI/CD. Un ejemplo con GitHub Actions:

name: Lint OpenAPI
on: [push, pull_request]
jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli
      - name: Lint OpenAPI document
        run: spectral lint openapi.yaml --ruleset .spectral.yaml --format junit > spectral-results.xml
      - name: Publish test results
        uses: EnricoMi/publish-unit-test-result-action@v2
        with:
          files: spectral-results.xml

Con la opción --fail-severity, puedes controlar qué niveles de gravedad hacen que el pipeline falle:

spectral lint openapi.yaml --fail-severity error

Esto permite que las advertencias pasen sin bloquear la compilación y, aun así, se muestren para su revisión.

Spectral en Stoplight Platform #

Stoplight Platform integra Spectral de forma nativa y ejecuta el linting en tiempo real mientras los diseñadores editan documentos OpenAPI en Stoplight Studio. Las infracciones de las reglas aparecen directamente en el editor, lo que facilita detectar y corregir los problemas durante la redacción en lugar de hacerlo en la fase de CI.

Conclusión #

Spectral es el estándar de facto para el linting de OpenAPI y la aplicación de guías de estilo. Ya sea para aplicar el conjunto de reglas de OpenAPI integrado, escribir reglas personalizadas específicas de la organización o publicar conjuntos de reglas compartidos en todo un programa de API, Spectral ofrece las herramientas necesarias para mantener descripciones de API coherentes y de alta calidad a gran escala. Integrar Spectral en los pipelines de CI/CD garantiza que cada cambio en la API se valide antes de llegar a los consumidores, lo que lo convierte en una parte esencial de cualquier flujo de trabajo maduro de gobernanza de API.

Última actualización: 29 de abril de 2026.