Uso de Spectral para eliminar la pelusa de su definición de OpenAPI

 

Los desarrolladores de API tienen mucho en qué centrarse, incluida la seguridad, los datos, el tiempo de respuesta, la optimización del código y muchas otras áreas. Pero uno de los aspectos más subestimados del diseño de API de calidad es la pelusa.

En términos generales, un linter es una herramienta que analiza el código fuente para descubrir errores, errores, problemas de estilo y código redundante. En términos de API, se pueden aplicar herramientas de pelusa para verificar errores dentro del proceso de diseño de API. Linting puede garantizar que la API no solo sea técnicamente perfecta, sino que también cumpla con las pautas estándar de la API.

Con el surgimiento de OpenAPI como una especificación de API estándar, los desarrolladores que utilizan OpenAPI deben asegurarse de que sus definiciones de API sigan la especificación. A continuación, explicaremos cómo filtrar sus definiciones OpenAPI YAML o JSON utilizando una herramienta de código abierto llamada Spectral.

Primero, ¿por qué es importante el pelaje?

• Estandarización de código : Linting le ayuda a seguir las pautas de codificación estándar. La estandarización del código puede reducir el desorden, ayudar a otros a comprenderlo y, en última instancia, ahorrar tiempo.
• Problemas de seguridad : los estándares suelen seguir medidas de seguridad específicas. Por lo tanto, pasar su código a través de un linter podría ayudar a reducir las lagunas o vulnerabilidades.
• Mejora del rendimiento : si los desarrolladores no siguen un estándar, la base de código puede volverse mucho más grande fácilmente, lo que da como resultado problemas de rendimiento y código de baja calidad. Linting puede ayudar a aumentar el rendimiento y garantizar un código de alta calidad.
• Buscar errores : imagina que escribiste cien líneas de código, pero no se ejecuta. Linting ayuda a identificar errores de código en tiempo real, lo que garantiza un código libre de errores de mayor calidad.
• Ahorro de tiempo : todos los puntos mencionados anteriormente nos llevan al beneficio máximo: ahorro de tiempo. El revestimiento puede reducir el tiempo de depuración, lo que resultará en un ahorro de tiempo.

¿Qué es espectral?

Spectral es una herramienta de revestimiento de especificación OpenAPI desarrollada por Spotlight. Es una herramienta completamente de código abierto disponible en Github con más de 700 estrellas en el momento de escribir este artículo.

Similar a Robocop y eslint, Spectral es un linter basado en terminal, lo que significa que no tiene una interfaz de usuario con la que trabajar. Con Spectral, los desarrolladores pueden filtrar las definiciones de OpenAPI v2 y v3 y crear guías de estilo automatizadas.

Ahora, intentemos ejecutar Spectral para lint:

Prerrequisitos

• Node.js

Paso 1: Instalar Spectral

Suponiendo que ya tiene Node.js instalado, abra la terminal y cree una carpeta con el nombre lint-apidel siguiente comando:

mkdir lint-api
cd lint-api

Ahora, instalemos Spectral. Para hacerlo, use el siguiente comando:

npm install -g @stoplight/spectral

Para validar la instalación, revisemos la versión de Spectral. Utilice el siguiente comando para verificar la versión:

spectral --version

Paso 2: Creación de una especificación de OpenAPI 3.1

Ahora, cree un archivo con el nombre test.yamly pegue el siguiente código:

openapi: 3.0.1
info:
  title: Employees API Spec
  description: Working with employee details
  version: v1
servers:
- url: http://localhost:8080/employees
  description: The employee api
tags:
- name: employee details api spec
paths:
  /api/v1/employees:
    summary: Employees
    description: API to work with employee details
    get:
      tags:
      - employees
      summary: Get list of employees
      description: Retrieve the list of employees and their details
      operationId: getEmployees
      responses:
        "200":
          description: request to get list of employees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponse'

Explicación del código:

Esta es una especificación de muestra de OpenAPI YAML que describe una API para la información de los empleados.

Paso 4: especificar un conjunto de reglas para la especificación

Ahora, cree un archivo con nombre rule.spectral.yamly pegue los siguientes conjuntos de reglas:

rules:
  oas3-api-servers:
    description: "OpenAPI `servers` must be present and non-empty."
    formats: ["oas3"]
    given: "$"
    then:
      field: servers
      function: schema
      functionOptions:
        schema:
          items:
            type: object
          minItems: 1
          type: array

Explicación del código:

Estas reglas definen el formato de la API, es decir oas3, que se utiliza para OpenAPI v3. También define el tipo y esquema de la API.

Paso 5: vincular la API

Ahora que ha definido una API y conjuntos de reglas, es el momento de lustrar la API. En su terminal, pegue el siguiente código para ejecutar el linter:

spectral lint test.yaml

Debería ver el siguiente resultado:

10:3  error  my-rule-one  Tags must have a description.                           tags[0]
 27:23  error  invalid-ref  '#/components/schemas/EmployeeResponse' does not exist  paths./api/v1/employees.get.responses[200].content.application/json.schema.$ref

✖ 2 problems (2 errors, 0 warnings, 0 infos, 0 hints)

Esta respuesta significa que algo anda mal con la especificación de la API. Intentemos corregir este problema. Para resolver el Tags must have a descriptionerror, solo necesitamos eliminar el primero tags.

Ahora intentemos volver a ejecutar el linter:

spectral lint test.yaml

Debería ver el siguiente resultado:

28:23  error  invalid-ref  '#/components/schemas/EmployeeResponse' does not exist  paths./api/v1/employees.get.responses[200].content.application/json.schema.$ref

✖ 1 problem (1 error, 0 warnings, 0 infos, 0 hints)

Este problema persiste porque el esquema en EmployeeResponserealidad no existe. Entonces podemos eliminar ese también. Para hacerlo, elimine la línea que dice $ref: '#/components/schemas/EmployeeResponse'del archivo test.yaml.

Intentemos volver a ejecutar el linter:

spectral lint test.yaml

¡Y bum! ¡No se encontraron errores!

OpenAPI 3.x detected
No results with a severity of 'error' or higher found!

Tenga en cuenta que Spectral también ha detectado la versión de la especificación OpenAPI automáticamente.

Ultimas palabras

Con una herramienta como Spectral, vincular una definición de API se vuelve muy sencillo. Pero la diversión no termina ahí: también puede usar Spectral para lustrar definiciones que no son de OpenAPI, incluida AsyncAPI. También puede crear conjuntos de reglas personalizados, lo que le permite definir nuevas reglas e incluso deshabilitar las reglas preexistentes también. Esta flexibilidad significa que el uso de Spectral para la definición de API tiene muchas ventajas.