Validar una spec OpenAPI 3 / Swagger en línea antes de la CI

¿Por qué validar una spec OpenAPI antes de hacer merge?

Una spec OpenAPI inválida bloquea los generadores de clientes, hace fallar los imports de pasarela API y retrasa las revisiones de contrato. Aun así, los errores más habituales — campo info incompleto, referencia $ref interna rota, versión openapi no soportada — suelen pasar desapercibidos en un diff YAML de varios cientos de líneas. El validador OpenAPI en línea de FastMinify comprueba la conformidad de esquema OpenAPI 3.0, 3.1 y 3.2 vía @scalar/openapi-parser, entero en el navegador. Pega JSON o YAML: el veredicto, las rutas de error y las estadísticas de la spec se muestran sin envío a servidor. Complétalo con el formateador OpenAPI para una revisión legible, y explora el hub de herramientas API. Si la sintaxis JSON bruta es dudosa, empieza por el validador JSON; para optimizar los payloads una vez validado el contrato, ver la guía de optimización de APIs REST.

Detección de errores de esquema OpenAPI 3.0–3.2 antes de la CI o el import de gateway

JSON y YAML aceptados — auto-detección con repliegue YAML si el JSON falla

Referencias internas <code>#/…</code> comprobadas; rutas de error Scalar mostradas

100 % local — la spec no sale del navegador (ideal para contratos internos)

Flujo rápido: validar → formatear → lintear → commit

Límites honestos y buenas prácticas

Lo que validate-openapi no hace

Un veredicto «válido» significa conformidad con el esquema OpenAPI — no que tu API responda correctamente en producción.

Sin fetch de $ref externas ni URL remotas

Sin bundle multi-archivo automático — una spec de un solo archivo por pegado

Sin validación Swagger 2.0

Sin test de seguridad (auth real, scopes efectivos)

Límite de entrada 512 KiB — las specs enormes requieren un puesto local o CI

Referencias internas vs externas

Las referencias #/ las comprueba Scalar. Las referencias HTTP(S) a otros archivos nunca se resuelven — la spec debe ser autónoma para una validación fiable en el navegador.

Prefiere un archivo único o haz el bundle aguas arriba con tu herramienta de CI

Una $ref externa no resuelta puede pasar el parse y fallar en otro sitio

Comprueba a mano los imports cross-repo después de la validación local

json-schema-to-openapi y openapi-to-json-schema en el hub para los pivotes de esquema

Para validar datos contra un esquema: json-schema-validator — ver también nuestra guía JSON Schema

Integración CI y complementos

La herramienta del navegador acelera el feedback antes del commit; la CI sigue siendo la fuente de verdad para los equipos.

Pega la spec modificada antes de git push — ahorro de tiempo frente al pipeline completo

En CI: spectral, openapi-cli o redocly según tu stack

Combínalo con la guía CI/CD para la automatización global

Documenta la versión OpenAPI objetivo (3.0 vs 3.1) en el README del repo

Revisa los breaking changes de esquema con json-diff sobre los exports JSON

OpenAPI 3 vs Swagger 2: lo que la herramienta comprueba (y rechaza)

OpenAPI 3.x: el contrato moderno

OpenAPI 3.x describe tus endpoints REST, esquemas de petición/respuesta, seguridad y componentes reutilizables. FastMinify valida la conformidad con el meta-esquema OpenAPI — no el comportamiento runtime de tu API.

Versiones soportadas: 3.0.x, 3.1.x, 3.2.x

Campos obligatorios típicos: openapi, info.title, info.version, paths

Componentes schemas, responses, parameters — referencias internas resueltas

Validación estructural Scalar — no un test de llamadas HTTP reales

YAML o JSON: misma semántica tras el parse

Swagger 2.0 rechazado de forma explícita

Los documentos con una clave raíz swagger: "2.0" no están soportados por esta herramienta. El mensaje de error es explícito — no intentes validarlos aquí.

Swagger 2 usa swagger; OpenAPI 3 usa openapi

Migración Swagger → OpenAPI 3: usa convertidores dedicados aguas arriba

FastMinify no pretende validar Swagger 2 — evita falsos positivos

Tras la migración, vuelve a validar con validate-openapi

Las specs híbridas o mal formadas fallan en el parse antes de la validación

Errores frecuentes en specs reales

Más allá de la sintaxis, son estas desviaciones estructurales las que hacen fallar la CI o los generadores SDK.

$ref interna que apunta a un componente inexistente — fallo de validación

Respuesta HTTP sin description — regla OpenAPI no respetada

operationId duplicado o ausente — bloquea algunos generadores

Esquema type incompatible con nullable / oneOf mal anidados

Mezcla de JSON Schema draft en components — errores de conformidad 3.1 vs 3.0

Validate vs lint vs format

Tres intenciones distintas en el hub API — no las mezcles en una revisión de PR.

Validate: conformidad de esquema OpenAPI (Scalar) — veredicto válido/inválido

Format: indentación y legibilidad — no corrige errores semánticos

Lint: reglas de estilo Spectral (operationId, tags…) — ver nuestra guía de lint y format OpenAPI

Orden recomendado: validate → format → lint antes del merge

El validador JSON solo no basta — una spec JSON sintácticamente válida puede ser OpenAPI inválido

Validar una spec OpenAPI: flujo paso a paso

Usar el validador OpenAPI

El validador OpenAPI parsea la entrada (JSON o YAML, máx. 512 KiB) y llama a Scalar validate(). Resultado: estado, primer error con línea si se conoce, lista de issues con rutas JSON Pointer.

Pega una spec de un solo archivo — sin fetch de URL externas

Validación con debounce en directo en el editor Monaco

Panel de resultados: veredicto, issues Scalar, stats de paths/operaciones

Las referencias <code>https://…</code> nunca se descargan — limitación voluntaria

Swagger 2.0 → mensaje de error claro, sin validación parcial

Formatear antes o después de validar

El formateador OpenAPI hace pretty-print en JSON o YAML (indentación 2 o 4 espacios, ordenación opcional de claves). Útil para una revisión humana — no sustituye validate.

Formato legible para PR — indentación coherente con el equipo

Opción de ordenar claves para diffs estables

Una entrada OpenAPI inválida puede formatearse igual si el parse funciona

Encadenar format → validate para localizar errores sobre una spec indentada

YAML voluminoso: comprueba el límite 512 KiB antes de pegar

Escenario — Spec rota antes del import API Gateway

Exportas una spec desde una herramienta de diseño y el import AWS API Gateway / Kong falla sin detalle.

Paso 1: Pegar en validate-openapi

Abre validate-openapi. Si el parse falla, corrige primero la sintaxis JSON/YAML — el validador JSON puede ayudar en la parte JSON.

Paso 2: Corregir las $ref internas

Las issues Scalar listan la ruta (#/components/schemas/User faltante, etc.). Corrige el typo o añade el componente referenciado.

Paso 3: Formatear y commit

Pasa la spec validada por format-openapi, descarga, abre la PR. Vuelve a importar en la pasarela.

Escenario — Revisión de contrato antes de generar SDK

El equipo mobile genera un cliente a partir de la spec — un error de esquema bloquea todo el pipeline.

Paso 1: Validar la versión mergeada

Pega la spec de la rama main en validate-openapi. Veredicto inválido → bloquea el tag de release.

Paso 2: Comprobar info y paths

Campos info completos, cada operación tiene responses con description. Las stats del panel de resultados ayudan a detectar paths vacíos.

Paso 3: Minificar los ejemplos JSON

Los ejemplos embebidos voluminosos ralentizan las revisiones — usa el minificador JSON sobre los payloads de ejemplo una vez validada la spec.

Conclusión

Validar una spec OpenAPI antes de la CI evita horas de debug en imports de gateway o generadores SDK silenciosos. Pega, valida, corrige las rutas Scalar — todo en local. Formatea para la revisión y explora el hub API para lint, conversión JSON Schema y validación GraphQL.

Validar tu spec OpenAPI ahora

Valida antes de cada PR que toque una spec OpenAPI

No uses esta herramienta para Swagger 2.0 — migra primero

Haz el bundle de las $ref externas aguas arriba para una validación fiable en el navegador

Encadena validate → format → lint para una revisión completa

Consulta la guía REST JSON para optimizar los payloads una vez el contrato esté sano