Dos ingenieros del mismo equipo lanzan dos endpoints en la misma semana. Uno devuelve created_at, el otro devuelve createdAt. Uno pagina con ?page=2, el otro con ?offset=20. Uno coloca los errores en un objeto error de nivel superior, el otro incrusta una cadena message. Ambos pasan la revisión de código, porque los revisores leen la lógica, no la nomenclatura. Seis meses después, la superficie de su API parece escrita por cinco empresas diferentes, y cada integración de cliente necesita un caso especial.
Un linter de OpenAPI existe para detectar esa divergencia antes de que se lance. Lee su documento OpenAPI, lo ejecuta contra un conjunto de reglas (las operaciones necesitan descripciones, los esquemas necesitan ejemplos, los nombres de propiedades siguen una convención de mayúsculas y minúsculas, cada respuesta declara un tipo de medio), y falla la compilación cuando se rompe una regla. Es la misma idea que ESLint para JavaScript o RuboCop para Ruby, pero apuntado a su contrato de API en lugar de su código de aplicación. Si alguna vez ha deseado que la revisión del diseño de la API pudiera automatizarse de la misma manera que el formato del código, eso es exactamente lo que hace un linter.
botón
Qué comprueba realmente un linter de OpenAPI
Un linter opera sobre el archivo de especificación, no sobre un servidor en ejecución. Apúntelo a openapi.yaml y recorrerá cada ruta, operación, parámetro, esquema y respuesta, aplicando las reglas una a la vez. Las reglas se dividen en varias categorías.
Validez. ¿Es este siquiera un documento OpenAPI legal? ¿Cada $ref se resuelve? ¿Están presentes las palabras clave requeridas? Esto se superpone con la validación de esquemas simple, y la mayoría de los linters lo hacen como base antes que cualquier otra cosa.
Completitud. ¿Cada operación tiene un operationId, un resumen y una descripción? ¿Cada parámetro se explica por sí mismo? ¿Cada esquema lleva un example? Estas son las reglas que hacen que la documentación y los SDK generados sean realmente utilizables, y son las que los humanos más olvidan.
Consistencia. Este es el verdadero premio. Los nombres de propiedades usan una convención de mayúsculas y minúsculas. Los segmentos de ruta son sustantivos plurales. Las respuestas de error comparten una forma. Cada respuesta 2xx declara application/json. Los códigos de estado se utilizan de la forma en que lo pretende la especificación HTTP. Ninguno de estos son errores de forma aislada; juntos son la diferencia entre una API que se siente diseñada y una que se siente ensamblada.
Estilo de la casa. Sus propias convenciones. Quizás cada endpoint debe estar etiquetado. Quizás DELETE debe devolver 204. Quizás los campos internos deben tener un prefijo. Estas son las reglas que nadie más tiene, y la capacidad de escribirlas es lo que distingue un linter con el que puede vivir de uno con el que lucha.
Una regla tiene una severidad: error, advertencia, información o sugerencia. Los errores fallan la compilación; las advertencias aparecen pero la dejan pasar. Ese selector de severidad es lo que le permite adoptar el linting en una API existente sin ahogarse en 4,000 violaciones el primer día. Empiece todo como advertencia, arregle lo peor y luego promueva las reglas a error a medida que avanza. Para el aspecto conceptual de por qué estas reglas importan y cómo los equipos las aplican a escala, el trasfondo más profundo se encuentra en cómo las principales empresas garantizan la consistencia del diseño de API.
Las principales opciones de linter de OpenAPI
Aquí están las herramientas que vale la pena conocer, con una lectura honesta sobre dónde encaja cada una.
Spectral
Spectral, de Stoplight, es el estándar de facto. Es una CLI y biblioteca de código abierto que aplica linting a OpenAPI 2.0 y 3.x (y AsyncAPI, y cualquier JSON o YAML a través de JSONPath). Viene con un conjunto de reglas incorporado spectral:oas que cubre las reglas de sentido común, y su verdadera fortaleza son las reglas personalizadas: usted describe qué verificar usando selectores given al estilo JSONPath más una función then, todo en un archivo YAML. Hay un gran catálogo de funciones incorporadas (truthy, pattern, casing, length, enumeration) y puede recurrir a JavaScript cuando necesite una lógica que el formato declarativo no puede expresar.
Fortalezas: está en todas partes, tiene el ecosistema de reglas más grande, existen extensiones de editor para VS Code y otros, y se ejecuta dondequiera que se ejecute Node. Si desea una herramienta que toda la industria reconozca, esta es. La desventaja es que escribir reglas no triviales significa aprender JSONPath y, finalmente, la API de funciones de Spectral. Tenemos un recorrido completo sobre eso en cómo construir reglas personalizadas de Spectral con TypeScript si desea profundizar en la autoría.
extends: ["spectral:oas"]
rules:
operation-operationId: error
operation-description: warn
property-casing:
description: Properties must be camelCase
given: $.components.schemas..properties[*]~
severity: error
then:
function: casing
functionOptions:
type: camel
npx @stoplight/spectral-cli lint openapi.yaml
CLI de Redocly
La CLI de Redocly combina el linting con el bundling y la vista previa de la documentación. Su linter lee una configuración redocly.yaml, incluye un conjunto de reglas incorporadas y admite conjuntos de reglas configurables más plugins personalizados escritos en JavaScript. Los equipos que ya usan Redocly para la documentación obtienen linting en la misma cadena de herramientas sin agregar una dependencia, y las reglas incorporadas se inclinan hacia lo que hace que la documentación se renderice bien.
Fortalezas: integración estrecha con un flujo de trabajo de documentación y bundling, valores predeterminados decentes y un formato de configuración que se siente familiar si vive en el ecosistema de Redocly. Si aún no está allí, la biblioteca de reglas es más pequeña que la de Spectral y la historia de las reglas personalizadas está menos documentada.
npx @redocly/cli lint openapi.yaml
Vacuum
Vacuum es un linter más nuevo escrito en Go, construido para la velocidad. Es compatible con los conjuntos de reglas de Spectral, por lo que puede apuntarlo a un .spectral.yaml existente y obtener las mismas comprobaciones ejecutándose mucho más rápido en especificaciones grandes. Para un monorepo con docenas de documentos API grandes, la diferencia de tiempo de ejecución es real.
Fortalezas: rápido, compatible con conjuntos de reglas de Spectral, binario único sin tiempo de ejecución de Node. Si su especificación es pequeña, la ganancia de velocidad es invisible, y el ecosistema y las herramientas del editor son más jóvenes que los de Spectral, por lo que es más atractivo como acelerador de CI que como una elección desde cero.
Swagger y openapi-spec-validator
Vale la pena nombrarlos para que no los confunda con linters. El Editor de Swagger y swagger-cli/openapi-spec-validator comprueban si un documento es un OpenAPI válido. Eso es solo validez, no consistencia o estilo de la casa. Aprobarán con gusto una especificación donde cada propiedad tiene un nombre diferente, porque nada en la especificación OpenAPI lo prohíbe. La validación es necesaria, pero es el piso, no el techo. Si está eligiendo entre herramientas de la familia Swagger y una plataforma de diseño completa, las ventajas y desventajas se exponen en alternativas a Swagger que también prueban su API.
Comprobaciones en tiempo de diseño en Apidog
Las herramientas anteriores se ejecutan después de que usted tiene un archivo. El otro lugar para detectar inconsistencias es antes de que exista el archivo, mientras está diseñando el endpoint. Apidog es una plataforma de diseño primero: usted construye endpoints y esquemas de datos en un editor visual, y mantiene su proyecto internamente consistente a medida que avanza. Los esquemas de datos reutilizables significan que el mismo modelo se referencia en todas partes en lugar de redefinirse por endpoint, lo que elimina toda una clase de divergencia de nomenclatura en la fuente. Los componentes de respuesta compartidos hacen lo mismo para las formas de error.
Apidog no es un reemplazo directo para un conjunto de reglas de Spectral; si ha comprometido reglas .spectral.yaml, siga ejecutándolas. Lo que Apidog cambia es cuánto encuentra su linter en primer lugar. Cuando la superficie de diseño impone la reutilización, el linter pasa de una pared de violaciones a una detección ocasional. Y debido a que Apidog importa y exporta OpenAPI 3.x estándar, el archivo que entrega a Spectral o Vacuum en CI es el mismo artefacto, por lo que las dos capas se apilan en lugar de competir.
Una configuración de linter que puede ejecutar hoy
Una buena configuración ejecuta la verificación en tres lugares, cada uno con un trabajo diferente. El editor brinda retroalimentación instantánea. El hook de pre-commit detiene errores obvios localmente. CI es la puerta que nadie puede saltarse. Aquí está cada capa.
Capa 1: el editor
Instale la extensión Spectral de VS Code y agregue un .spectral.yaml a la raíz de su repositorio. La extensión lo detecta automáticamente y subraya las violaciones a medida que edita la especificación, de la misma manera que un error tipográfico obtiene un subrayado rojo. Este es el bucle de retroalimentación más económico posible, porque el desarrollador corrige el problema antes de que se convierta en un commit. Nada más que configurar; el archivo en el repositorio es la única fuente de verdad sobre cuáles son las reglas.
Capa 2: pre-commit
Agregue un hook para que una especificación rota nunca llegue al repositorio remoto. Usar un script package.json más un hook de Git es suficiente:
{
"scripts": {
"lint:api": "spectral lint openapi.yaml --fail-severity=error"
}
}
# .git/hooks/pre-commit (o vía husky)
#!/bin/sh
npm run lint:api || {
echo "OpenAPI lint failed. Fix the spec before committing."
exit 1
}
El flag --fail-severity=error es la parte importante. Le indica al linter que salga con un código distinto de cero solo en caso de errores, por lo que las advertencias se siguen mostrando sin bloquear el commit. Esto mantiene el hook utilizable mientras sigue promoviendo reglas.
Capa 3: CI
Esta es la puerta que importa, porque es la que un compañero de equipo no puede omitir con --no-verify. Un paso de GitHub Actions:
name: API lint
on: [pull_request]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx @stoplight/spectral-cli lint openapi.yaml --fail-severity=error
La tarea falla cuando la especificación rompe una regla de nivel de error, la solicitud de extracción muestra una marca roja y la fusión se bloquea hasta que alguien lo solucione. Ese es todo el mecanismo de aplicación. Sin paneles, sin quejas; la regla es verde o no lo es.
Capa 4: probar la API que describe la especificación
Un linter demuestra que la especificación está bien formada y es consistente. No dice nada sobre si la API en ejecución coincide con la especificación. Esa brecha es donde se esconde la desviación del contrato: un documento bellamente linted que describe un comportamiento que el servidor dejó de respetar hace tres lanzamientos. Para cerrarla, debe ejecutar pruebas contra la API en vivo en el mismo pipeline.
Aquí es donde la CLI de Apidog encaja junto a su linter. Es un paquete npm, apidog-cli, y ejecuta sus escenarios de prueba de Apidog desde la línea de comandos para que encajen en CI justo después del paso de linting:
npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
El comando apidog run sale con un código distinto de cero cuando una prueba falla, el mismo contrato en el que se basa cada paso de CI, por lo que una prueba fallida bloquea la fusión exactamente de la misma manera que un linting fallido. El reportero -r junit emite XML que su panel de CI analiza en un árbol de aprobación/falla, y -e apunta los mismos escenarios a entornos de prueba o producción sin duplicarlos. La CLI también puede importar un documento OpenAPI 3.x, por lo que el archivo que su linter verifica es el mismo archivo contra el que Apidog realiza las pruebas. Para el patrón de pipeline completo, incluyendo reporteros y manejo de códigos de salida, consulte la guía sobre cómo ejecutar la CLI de Apidog en su pipeline de CI/CD. Si está específicamente en GitHub, la CLI de Apidog en GitHub Actions tiene un flujo de trabajo de copiar y pegar.
Linting primero, prueba después. El paso de linting es rápido y detecta problemas de diseño; el paso de prueba es más lento y detecta problemas de comportamiento. Ejecútelos como dos etapas y una solicitud de extracción tendrá que pasar ambas.
Elegir y adoptar un conjunto de reglas sin dolor
Elegir la herramienta es la parte fácil. Adoptarla en una API que ya existe es donde los equipos se estancan, porque la primera ejecución en una especificación madura devuelve cientos de violaciones y la reacción obvia es apagarlo todo.
No empiece desde cero reglas y no empiece con todas las reglas en error. Comience con el conjunto de reglas incorporado (spectral:oas) con todo lo que agregue configurado en warn. Ejecútelo, lea el recuento y corrija primero los errores de validez porque son errores reales. Luego, elija las dos o tres reglas de consistencia que más importan a sus clientes (generalmente el estilo de mayúsculas y minúsculas de las propiedades y una única forma de error) y promueva solo esas a error. Todo lo demás permanece como advertencia. Cada sprint, promueva una o dos advertencias más a errores a medida que el código base se pone al día. En un trimestre, todo el conjunto de reglas estará aplicado y nadie tuvo que dejar de desarrollar para lograrlo.
Escriba las reglas de estilo de la casa con moderación. Cada regla personalizada es código que alguien tiene que mantener y explicar al siguiente empleado. Una regla se gana su lugar solo cuando una violación realmente le ha afectado, no porque podría. Para las reglas que escriba, apóyese en la capa de diseño para hacerlas raras: si sus esquemas se reutilizan de una definición central, una regla de estilo de mayúsculas y minúsculas de propiedad casi nunca se dispara porque hay un solo lugar donde se define el nombre. El marco conceptual sobre qué reglas vale la pena aplicar, versus cuáles son triviales, se cubre en mejores prácticas de diseño de API.
Si diseña en un lenguaje diferente al YAML puro, el linter sigue siendo aplicable. TypeSpec se compila a OpenAPI, y se aplica el linting al documento emitido de la misma manera; al linter no le importa cómo se creó el archivo, solo lo que dice.
Dónde encaja el linter en el ciclo de diseño más amplio
Un linter es un control en un flujo de trabajo de diseño primero, no la totalidad. El ciclo completo es: diseñar el contrato, aplicarle linting, simularlo para que los clientes puedan construir sobre él, probar la implementación contra él y publicar la documentación a partir de él. Si se salta cualquier paso, los demás pierden valor. Una especificación con linting que nadie simula aún bloquea el trabajo de frontend. Una especificación simulada que nadie prueba aún se desvía de la realidad.
La razón para priorizar el diseño en ese ciclo es la misma razón por la que funciona el linting: detectar problemas donde son más baratos de solucionar. Cambiar el nombre de una propiedad en la herramienta de diseño es una edición. Cambiarlo después de que tres equipos hayan lanzado usando el nombre antiguo es una migración. El linter aplica consistencia en el archivo; un proceso de diseño primero lo aplica en la decisión antes de que exista el archivo. Si desea el argumento más amplio para la secuenciación, API-first vs API design-first vs code-first expone las ventajas y desventajas, y herramientas de diseño de API contract-first cubre las herramientas que lo soportan.
botón
Apidog cubre todo ese ciclo en un solo lugar: diseño con esquemas reutilizables, simulación instantánea, prueba con la CLI en CI y exportación de OpenAPI limpio para cualquier linter que estandarice. El linter todavía tiene un trabajo; solo hay menos cosas que detectar.
botón