Spectral Rules para AsyncAPI: Calidad y Gobierno en tus Contratos Asíncronos
¿Qué es spectral-rules-asyncapi?
El proyecto spectral-rules-asyncapi es un ruleset de Spectral diseñado para validar y gobernar documentos AsyncAPI 2.x y 3.x. Desarrollado por ApiQuality y distribuido a la comunidad APIAddicts, proporciona 28 reglas listas para usar que cubren seguridad, operaciones y calidad documental en APIs asíncronas.
El repositorio es la contrapartida AsyncAPI del popular apiaddicts-style-guide-spectral para OpenAPI, y traduce directamente las reglas del plugin SonarQube sonarasyncapi-rules al ecosistema Spectral.
Por qué el gobierno de APIs asíncronas importa
Las APIs REST llevan años beneficiándose de herramientas de linting y gobernanza. Las APIs asíncronas —basadas en Kafka, MQTT, WebSockets o AMQP— aún acumulan deuda histórica en este área. Sin validación automática, los equipos entregan documentos AsyncAPI sin servidores HTTPS, sin esquemas de seguridad, sin operationId únicos o con descripciones en blanco: exactamente los errores que detecta este ruleset.
Integrar spectral-rules-asyncapi en el pipeline de CI/CD convierte esos errores en fallos de build antes de que lleguen a producción.
Categorías de reglas incluidas
Seguridad (4 reglas): Exigen HTTPS o protocolo seguro en todos los servidores (AAR001), obligan a definir la sección servers (AAR008), validan los tipos de esquema de seguridad (AAR018) y recomiendan que cada operación declare un esquema de seguridad (AAR043).
Operaciones (4 reglas): Requieren al menos una etiqueta por operación (AAR009), descripciones en las etiquetas (AAR010), que los servidores de canal referencien servidores raíz (AAR040) y promueven el uso de components para reutilización (AAR041).
Formato y documentación (16 reglas): Cubren licencia, operationId único y sin duplicados, sección contact, restricciones en tipos numéricos y cadenas, formato de descripciones, bindings con bindingVersion y más.
Esquemas (3 reglas): Validan que los ejemplos de mensajes cumplan el esquema de payload, promueven el uso de $ref en components.messages y verifican ejemplos contra headers y payload declarados.
Soporte para AsyncAPI 2.x y 3.x
Una de las características más destacadas es el soporte dual. Todas las reglas funcionan sobre AsyncAPI 2.x por defecto. Para AsyncAPI 3.x, donde las operaciones han migrado de channels[*].publish/subscribe a operations[*] (nivel raíz), el ruleset incluye variantes con sufijo -v3 que se aplican automáticamente según el formato del documento.
Funciones personalizadas incluidas
El ruleset incorpora 9 funciones JavaScript personalizadas para lógica de validación compleja: detección de operationId duplicados entre canales, validación de ejemplos de mensaje contra esquemas JSON, verificación de restricciones en tipos numéricos y cadenas, comprobación de referencias de servidores en canales, y análisis del formato de descripciones (mayúscula inicial, punto final).
Cómo empezar en 3 pasos
Instala Spectral CLI con npm install -g @stoplight/spectral-cli, crea un archivo .spectral.yaml en la raíz de tu proyecto referenciando el ruleset remoto, y lanza el linter sobre tu contrato AsyncAPI:
spectral lint tu-asyncapi.yamlTambién puedes instalar la extensión de VSCode de Spectral para obtener validación en tiempo real mientras editas tus contratos.
Parte del ecosistema APIAddicts
Este proyecto se integra con el resto de herramientas open source de APIAddicts: comparte convenciones con apiaddicts-style-guide-spectral (OpenAPI) y sus reglas son la traducción directa del plugin SonarQube sonarasyncapi-rules. El objetivo es que cualquier equipo aplique las mismas políticas de calidad en el linter local y en SonarQube.
El repositorio está disponible en github.com/apiaddicts/spectral-rules-asyncapi bajo licencia GPL-3.0. La versión 1.0.0 fue publicada el 30 de abril de 2026.
