
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-api
del 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.yaml
y 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.yaml
y 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 description
error, 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 EmployeeResponse
realidad 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.
0 Comentarios
Dejanos tu comentario para seguir mejorando!