En este quinto artículo de Spectral aprenderemos a incorporar el lintado de Spectral como parte del ciclo de construcción de un proyecto Node.js.

A modo de recordatorio pongo los enlaces a los artículos :

• Primeros pasos con Spectral (Parte 1) : Artículo de introducción a la herramienta Spectral que hace uso de diferentes ejemplos y que explica diferentes enfoques de diseño.

• Primeros pasos con Spectral (Parte 2): Implementar una Regla Custom: Artículo que enseñará la forma de crear una regla customizada y usarla mediante una propuesta de procedimiento sobre la forma de hacerse.

• Primeros pasos con Spectral (Parte 3): Desarrollando APIs: Artículo que enseñará a como enfocar Spectral al desarrollo de APIs.

• Primeros pasos con Spectral (Parte 4): Guía de Estilo de APIs: Artículo que enseñará a implementar Spectral como una guía de estilos de APIs con diferentes enfoques.

Este es el índice que se va a utilizar para estructurar este artículo

• Creación de un Proyecto Node.js
• Integración del proyecto con Spectral
• Ejemplo de Uso
• Conclusiones

Creación de un Proyecto Node.js

En este apartado vamos a crear un proyecto desde 0 para el desarrollo de una API Web OAS3 sobre Node.js.

Definición de tareas iniciales del proyecto

En primer lugar, vamos a crear un proyecto vacio en Node.js.

Pasos a seguir:

1. Arrancar el terminal

2. Crear y seleccionar un directorio de trabajo con el nombre que tendrá el proyecto (Por ejemplo: spectral-project)

mkdir <nombre-proyecto>
cd <nombre-proyecto>

#Ejemplo
mkdir spectral-project
cd spectral-project

3. Verificar que nos encontramos en el directorio de trabajo

4. Ejecutar el siguiente comando :

npm init -y

5. Verificar que se ha creado el fichero package.json

6. Crear los directorios dentro del proyecto :

   • "examples/"
   • "config/"
     • "spectral/"
       • "rules/

7. Verificar la creación de dichos directorios

Definición de tareas del ciclo de desarrollo del proyecto

Se añadirá al fichero "package.json" los siguientes built-in:

"scripts": {
    "clean": "rm -rf package-lock.json && npm install",
    "node:version": "echo 'nodejs version: ' && node -v "
},

Tareas :

clean : Clean e install del proyecto (eliminando el fichero de bloqueo de construcción)

$ npm run clean

Verificar que se genera el fichero "package-lock.json" y el directorio "node_modules".

node:version : Verificación de la versión de node con la que se trabaja

$ npm run node:version

Con esto ya tendríamos disponible el proyecto para empezar a configurarlo.

Integración del proyecto con Spectral

En este punto añadiremos la herramienta Spectral como dependencia dentro del proyecto, para posteriormente generar una o varias tareas para trabajar con ella.

Instalar dependencias de Spectral

Pasos a seguir:

1. Ejecutar el siguiente comando:

# Install Spectral Core as development dependency
npm install --save-dev @stoplight/spectral-core

2. Verificar que se refleja la instalación de la dependencia sobre el fichero "package.json"

Definir e implementar el fichero de configuración de Spectral

En este punto se va a decidir cómo se va a representar el fichero de configuración de Spectral que utilizaremos en el proyecto

Pasos a seguir:

1. Crear el fichero sobre el directorio del proyecto ".spectral.yml"

Fichero por defecto de spectral y que se proporcionará a nivel del proyecto

2. Incorporar el contenido siguiente al fichero

extends:
- spectral:oas
- ./spectral/rules/open-api-version-3.yaml
rules: {}

3. Crear el directorio "rules" sobre el directoro "spectral" (sino se ha creado): config/spectral/rules

4. Crear el fichero "open-api-version-3.yaml"

5. Incorporar sobre el fichero el contenido

rules:
    open-api-version-3:
        description: APIs should support OpenAPI V3
        given: $.openapi
        severity: error
        then:
            function: pattern
            functionOptions:
                match: '^3'

Importante
Esta regla custom se definió en el segundo artículo de la serie, si se tiene alguna duda se puede acceder al Primeros pasos con Spectral (Parte 2): Implementar una Regla Custom: Artículo que enseñará la forma de crear una regla customizada y usarla mediante una propuesta de procedimiento sobre la forma de hacerse.

Configurar tareas de Spectral en el ciclo de desarrollo del proyecto

En este apartado configuraremos la/s tarea/s que queremos lanzar desde Node.

Pasos a realizar:

1. Identificar qué tipo de análisis queremos ejecutar

Por ejemplo :

spectral lint ./examples/example1.yaml

En este caso, se muestra el comando de ejecución de un análisis sobre el fichero "./examples/example1.yaml" con el conjunto de reglas definido en el fichero por defecto ".spectral.yaml".

Según las necesidades que podamos tener podemos usar todas las opciones permitidas en los parámetros de ejecución como:

• Usar una expresión glob
• Forzar la parada ante un error
• ...

# Ejemplo de expresión glob
spectral lint ./examples/*

# Ejemplo de expresión glob y de forzar la salida con error para "warn"
spectral lint -F warn ./examples/*

2. Generar una o varias tareas del proyecto sobre el fichero "package.json"

"scripts": {
    ...
    "spectral:oas:lint:one": "spectral lint ./examples/example1.yaml",
    "spectral:oas:lint": "spectral lint ./examples/*",
    "spectral:oas:lint-warning-as-errors": "spectral lint -F warn ./examples/*"
  },

Para ello le daremos un nombre al comando node de ejecución y estableceremos el comando de ejecución de Spectral que cubre nuestras necesidades.

3. Probar las operaciones anteriores desde la línea de comandos

Ejemplo de Uso

Para enseñar a utilizarlo y así practicar se ha habilitado un repositorio, este repositorio se reutilizará para otros artículos con Spectral.

La parte de que tiene que ver con este artículo se encuentra en el apartado de spectral-project/

Conclusiones

En este artículo hemos aprendido a instalar y configurar Spectral dentro de un proyecto Node.js, lo que cambia un poco con lo aprendido anteriormente donde Spectral se instalaba de forma global a todas las instalaciones.

Por otro lado, se ha aprendido a incluir las operaciones de lintado con Spectral como operaciones de built-in dentro del ciclo de desarrollo, con lo que ahora formará parte directa en el proceso de construcción y no como una tarea de ejecución externa, con lo que se nos habré un mundo de posibilidades a la hora de hacer uso de ellos en los proyectos.

Lo siguientes artículos tratarán de continuar trabajando en esta línea de trabajo que tiene que ver con los proyectos.

Continuamos danto pasitos...