OpenAPI: lint, formateo y estructura de una API mantenible
operationId, tags, responses de error: las reglas que evitan deuda cuando linteas y formateas specs OpenAPI.
¿Por qué lintear y formatear una spec OpenAPI antes de hacer merge?
Una spec puede pasar la validación de esquema y aun así salir sin operationId, sin tags o con solo una respuesta default — y esa deuda técnica aparece semanas después, cuando los generadores SDK, portales API o tests de contrato fallan en silencio. El formateo solo no cubre esas lagunas; el lint detecta reglas de estilo y de completitud que los validadores ignoran. El linter OpenAPI en línea de FastMinify aplica un subconjunto Spectral fijo sobre las operaciones de paths, entero en el navegador. Combínalo con el formateador OpenAPI para diffs de PR legibles y con el validador OpenAPI para la conformidad de esquema. Empieza por nuestra guía de validación OpenAPI si te bloquean errores estructurales, y luego explora el hub de herramientas API.
Límites honestos y diseño de API mantenible
Un estado lint passed significa ninguna issue en el subconjunto v1 — no que tu API esté lista para producción ni documentada por completo.
Estos campos evitan una deuda de spec que los validadores no ven pero que generadores y portales exigen.
operationId: estable, único, camelCase — evita renombrados sin un plan de deprecacióntags: agrupación por dominio o bounded context — alineado con las secciones del portal devinfo.description e info.contact: el lint avisa si faltan — rellena para APIs externas/pet-orders a /petOrders — regla kebab-case alineada con RESTLas herramientas del navegador aceleran el feedback; los pipelines imponen la política de la organización.
$ref externasDesign-first: validar, formatear y después lintear
No intercambies los pasos en la revisión — cada herramienta responde a una pregunta distinta sobre tu archivo OpenAPI.
El lint de FastMinify no es Spectral completo — entrega un conjunto fijo de reglas centrado en operaciones de paths mantenibles (ADR-OAS-009).
not-openapi (error): la raíz debe ser OpenAPI 3.x con un objeto info — puerta de entrada antes del resto de reglasinfo-contact (warning): info.contact debería estar presenteinfo-description (warning): info.description no vacíopaths-kebab-case (warning): segmentos de path en kebab-case o vNoperation-operationId (warning): cada operación tiene un operationId no vacíooperation-tags (warning): al menos un tag por operaciónoperation-description (warning): summary o description requeridosoperation-success-response (error): al menos una respuesta 2xx — default solo no bastapath-item-ref (warning): $ref de path item no expandida en lint v1Alcance honesto — no asumas paridad con Spectral, Redocly o los motores de política de gateway.
webhooks y callbacks fuera de alcance v1$ref externas — pega una spec autónomaEl formateador hace pretty-print en JSON o YAML (indentación 2 o 4 espacios) y puede ordenar las claves de forma recursiva para diffs estables.
openapi: 3.0 numérico en YAML se normaliza a cadena 3.0.0Lintear y formatear OpenAPI: flujo paso a paso
El linter OpenAPI parsea JSON o YAML (máx. 512 KiB), comprueba la puerta not-openapi y luego ejecuta las reglas sobre las operaciones. Estado: passed, passed with warnings o failed — nunca un verde simple cuando hay warnings.
El formateador OpenAPI hace pretty-print para una revisión humana. Auto-format al pegar; botón Format (⌘↵) tras una edición manual.
Tu pipeline mobile genera un cliente desde la spec — los warnings ignorados se convierten en fallos aguas abajo.
Paso 1: Validar la conformidad de esquema
Pega en validate-openapi. Corrige primero los errores Scalar — el lint no ayuda sobre una spec estructuralmente inválida.
Paso 2: Lintear las operaciones de paths
Abre lint-openapi. Resuelve los warnings operation-operationId y operation-tags en cada endpoint público.
Paso 3: Formatear y abrir la PR
Pasa la spec corregida por format-openapi con ordenación de claves si el equipo la usa. Vuelve a lintear antes del commit.
Un diseñador exporta YAML minificado — los revisores no ven los renombrados accidentales de paths.
Paso 1: Formatear para la legibilidad
Pega en format-openapi, indentación 2 espacios, ordenación de claves si el equipo está de acuerdo.
Paso 2: Validar y luego lintear
Valida con Scalar y después lintea para paths-kebab-case y operation-success-response en los endpoints nuevos.
Paso 3: Documentar las respuestas de error
El lint exige la presencia 2xx — añade a mano 4xx/5xx con descriptions para contratos de producción (fuera de los errores lint v1).
Flujo de revisión PR: del design-first al merge
Trata el trío del navegador como puerta rápida antes de git push — la CI sigue siendo la fuente de verdad del equipo, pero detectar en local ahorra minutos de pipeline. Orden: (1) validate-openapi — corregir los errores Scalar; (2) format-openapi — diff legible; (3) lint-openapi — resolver los errores y después los warnings según la política del equipo; (4) commit.
Más allá del validate en verde, pregunta: ¿los operationId son únicos y estables para el codegen? ¿Los tags coinciden con la navegación del portal API? ¿Cada operación documenta al menos una respuesta de éxito — y las formas de error habituales para los equipos cliente?
En CI, los equipos suelen ejecutar Spectral, openapi-cli o Redocly con rulesets más estrictos que FastMinify v1. Combina el lint del navegador con nuestra guía CI/CD. Para pivotes de esquema: json-schema-to-openapi y openapi-to-json-schema en el hub. Para validar payloads contra un esquema una vez el contrato está sano: consulta nuestra guía de validación JSON Schema.
Conclusión
Las specs OpenAPI mantenibles exigen más que la validación de esquema: el lint captura las lagunas de operationId, tags y responses que bloquean los generadores, y el formateo mantiene las PR revisables. Valida primero, formatea para humanos, lintea para el estilo — todo en local antes de la CI. Explora el hub API para la conversión JSON Schema y la validación SDL GraphQL cuando tu trabajo de contrato vaya más allá de REST.
Artículos relacionados
YAML roto, `on` o `jobs` ausentes, steps vacíos: valida la estructura de tus workflows antes del push — y deja actionlint para la CI.
Errores de sintaxis SDL, review de esquema y formateo antes del merge — complemento al beautify GraphQL existente.
Reduce la factura OpenAI/Anthropic/Gemini: estima input/output, activa batch y caching en tus cálculos — tarifas verificadas, 100 % local.