Validador OpenAPI: Verificar tu Spec API

¿Qué es el Validador OpenAPI?

El Validador OpenAPI es una herramienta basada en navegador que analiza y valida archivos de especificación OpenAPI 3.x y Swagger 2.0. Pegue una spec en JSON o YAML, haga clic en Validate, y en segundos verá si la spec es estructuralmente válida, un conteo de rutas y operaciones, y una lista de advertencias sobre campos faltantes que importan para generadores de SDK y herramientas de documentación para desarrolladores.

La herramienta se ejecuta completamente en su navegador usando la biblioteca @readme/openapi-parser cargada bajo demanda. Ningún contenido de la spec se envía a ningún servidor. Es gratuita sin necesidad de cuenta.

Úsela antes de hacer commit de una spec al control de versiones, antes de publicar documentación de API, o al depurar una spec que una herramienta posterior como Swagger UI, Stoplight o un generador de SDK está rechazando.

Características principales

• Soporte para OpenAPI 3.x y Swagger 2.0: El validador acepta ambos formatos. La biblioteca subyacente @readme/openapi-parser maneja ambas versiones de especificación, incluyendo OpenAPI 3.1.
• Entrada JSON y YAML: La herramienta intenta JSON.parse primero, luego recurre a js-yaml para entrada YAML. No necesita declarar qué formato está usando.
• Validación estructural con mensajes de error precisos: Cuando la validación falla, los mensajes de error del parser se dividen por saltos de línea y se muestran individualmente, cada uno con una referencia de ruta donde corresponda.
• Advertencias de linting: Incluso cuando una spec es estructuralmente válida, la herramienta verifica tres problemas de calidad comunes: info.description faltante, operaciones sin description ni summary, y operaciones sin operationId (requerido para generación de SDK). Cada advertencia muestra un conteo para que conozca el alcance del problema.
• Conteos de endpoints y operaciones: Después de una validación exitosa, mosaicos de resumen muestran el título de la API, cadena de versión, conteo total de rutas y conteo total de operaciones (a través de todos los métodos HTTP: get, post, put, patch, delete, head, options, trace).
• Botón Cargar Ejemplo: Inserta una spec OpenAPI 3.0 mínima pero completa con un único endpoint GET /users para que pueda ver cómo luce una salida válida antes de pegar su propia spec.
• Historial de validación: Las specs anteriores se guardan en la base de datos IndexedDB del navegador (función de supporter) para que pueda revisarlas o restaurarlas sin volver a pegarlas.
• Procesamiento 100% del lado del cliente: El parser y validador se ejecutan en el navegador. El contenido de la spec nunca sale de su máquina.

Cómo usar el Validador OpenAPI

Paso 1: Pegar su Spec

Haga clic dentro del área de texto grande etiquetada "OpenAPI Specification (JSON or YAML)" y pegue el contenido de su spec. El campo acepta YAML o JSON sin formato. Para YAML, incluya la declaración de versión en la parte superior (openapi: "3.0.0" o swagger: "2.0"). El área de texto es monoespaciada y muestra aproximadamente 15-20 líneas visibles.

Si desea ver la herramienta en acción antes de usar su propia spec, haga clic en el botón "Load Example" en la esquina superior derecha del área de texto. Carga una spec OpenAPI 3.0 mínima con un endpoint GET /users que devuelve un array de objetos de usuario.

Paso 2: Hacer clic en Validate Spec

Haga clic en el botón "Validate Spec" debajo del área de texto. El botón muestra "Validating..." mientras el parser está ejecutándose (las bibliotecas @readme/openapi-parser y js-yaml se cargan dinámicamente en el primer uso, por lo que la primera validación puede tardar un poco más que las siguientes).

La validación se ejecuta contra la spec completa en memoria. Para entrada YAML, la herramienta primero la convierte a un objeto JavaScript con js-yaml, luego pasa el objeto al parser OpenAPI.

Paso 3: Revisar el resultado de validación

El panel de resultado aparece debajo del botón con uno de dos encabezados:

• "✓ Valid OpenAPI Specification" en verde — la spec pasó la validación estructural.
• "✗ Validation Failed" en rojo — la spec tiene errores estructurales que deben corregirse.

El encabezado del panel también muestra contadores de badges: badges rojos para errores, badges amarillos para advertencias. Puede tener una spec válida con advertencias — las advertencias indican mejoras de calidad, no fallos estructurales.

Paso 4: Leer los mosaicos de resumen (Specs válidas)

Para specs que pasan la validación, aparecen cuatro mosaicos de resumen sobre la lista de errores/advertencias:

• Title — el valor de info.title
• Version — el valor de info.version
• Paths — número total de entradas de rutas (ej., /users, /users/{id})
• Operations — número total de combinaciones método HTTP+ruta (ej., una ruta con GET y POST cuenta como 2)

Estos números son útiles para confirmar que está validando el archivo correcto, especialmente al gestionar múltiples versiones de specs.

Paso 5: Abordar advertencias

Se muestran tres tipos de advertencias incluso en specs válidas:

1. info.description faltante — la spec carece de una descripción general de la API. Esto aparece en Swagger UI y portales de desarrolladores y ayuda a los usuarios a entender qué hace la API.
2. Operaciones sin description o summary — reportado como conteo (ej., "3 operation(s) missing description or summary"). Se verifican tanto description como summary; si cualquiera está presente, no se genera advertencia para esa operación.
3. Operaciones sin operationId — los generadores de SDK (OpenAPI Generator, Kiota, etc.) usan operationId para nombrar los métodos generados. Los valores faltantes hacen que los generadores recurran a nombres basados en rutas, que suelen ser verbosos e inconsistentes.

Ejemplos prácticos

Ejemplo 1: Encontrar un campo requerido faltante

Suponga que pega una spec Swagger 2.0 que referencia un $ref que apunta a una definición de esquema que no existe. El validador devolverá:

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

Cada línea del error del parser se muestra como una entrada de error separada. Corrija la ruta del $ref o agregue la definición faltante, luego vuelva a validar.

Ejemplo 2: Spec válida con advertencias de calidad

Una spec con todos los elementos estructurales requeridos pero sin valores operationId en sus endpoints pasa la validación pero muestra:

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

La spec puede usarse en herramientas como Swagger UI inmediatamente. Aborde las advertencias antes de ejecutarla a través de un generador de SDK.

Ejemplo 3: Verificar una spec grande de un vistazo

Después de pegar una spec de API interna con 500 rutas, los mosaicos de resumen muestran "Paths: 147" y "Operations: 312". Si esperaba 150 rutas, sabe que debe investigar por qué faltan tres rutas antes de hacer commit de la spec.

Consejos y buenas prácticas

Valide después de cada cambio estructural. Agregar una nueva ruta, cambiar un $ref o modificar un esquema puede introducir errores que solo aparecen cuando se parsea la spec completa. La validación toma menos de dos segundos, así que ejecútela frecuentemente.

Trate las advertencias de operationId como bloqueadores para flujos de SDK. Si está generando SDKs de cliente desde su spec, todas las operaciones deben tener valores operationId únicos. Dejarlos sin establecer significa que los nombres de métodos generados se derivarán de rutas (ej., getUsersUserIdOrders en lugar de listOrders), lo cual es difícil de manejar.

Use el ejemplo cargado como plantilla inicial. El ejemplo integrado es una spec OpenAPI 3.0 completa, válida y mínima. Cópiela del área de texto después de cargarla y úsela como esqueleto para una nueva spec en lugar de comenzar desde un archivo vacío.

Separe la validez estructural de la corrección semántica. El validador confirma que su spec sigue el esquema OpenAPI. No confirma que su spec describe con precisión su API real. Ejecute pruebas de integración o pruebas de contrato para verificar la precisión semántica.

Corrija errores de arriba hacia abajo. Una única definición de esquema faltante puede causar errores $ref en cascada en toda la spec. Aborde el error raíz primero y vuelva a validar antes de trabajar en errores secundarios.

Problemas comunes y solución de problemas

"Parse error: ..." — la entrada no es JSON válido ni YAML válido. Causas comunes: una coma final en JSON ({"key": "value",}), indentación YAML inconsistente, o un carácter de tabulación usado para indentación YAML (YAML requiere espacios). Corrija la sintaxis y vuelva a validar.

La validación falla en una spec que Swagger UI acepta. Swagger UI es tolerante y renderizará specs con algunas violaciones estructurales. El @readme/openapi-parser aplica validación estricta según el JSON Schema oficial para OpenAPI. Los errores mostrados aquí reflejan violaciones reales de la especificación incluso si Swagger UI las ignora silenciosamente.

Las advertencias aparecen incluso después de agregar descripciones. La herramienta verifica tanto description como summary en operaciones, pero verifica info.description por separado. Confirme que agregó description dentro de info, no solo en rutas individuales.

La herramienta parece lenta en el primer uso. Las bibliotecas @readme/openapi-parser y js-yaml se cargan dinámicamente en el primer clic de validación. Las validaciones posteriores en la misma sesión del navegador serán más rápidas porque los módulos ya están en memoria.

Los mensajes de error largos se cortan. Los mensajes de error del parser se muestran completos. Si un mensaje es largo, el texto se ajusta dentro de su fila. Desplácese por la página para leer el mensaje completo si se extiende debajo del área visible.

Privacidad y seguridad

El Validador OpenAPI procesa su spec completamente en el navegador. La biblioteca @readme/openapi-parser se ejecuta localmente — ningún contenido de la spec se envía a ningún servicio externo o servidor. Esto significa que puede validar de forma segura specs de API internas, rutas de endpoints privados y definiciones de esquemas propietarios sin riesgo de exposición. La herramienta funciona completamente offline una vez que la página y la biblioteca del parser se han cargado.

Preguntas frecuentes

¿Es gratuito el Validador OpenAPI? Sí. No hay costo, cuenta ni límite de uso. Todas las funciones de validación están disponibles sin iniciar sesión.

¿Qué versiones de OpenAPI son soportadas? La herramienta acepta Swagger 2.0, OpenAPI 3.0.x y OpenAPI 3.1.x. El @readme/openapi-parser subyacente maneja las tres versiones. El placeholder del área de texto indica "OpenAPI 2.0 / 3.0 / 3.1" para reflejarlo.

¿Puedo pegar YAML o necesita ser JSON? Ambos formatos funcionan. La herramienta intenta JSON.parse primero, y si falla usa js-yaml para parsear YAML. No necesita convertir su spec antes de pegarla.

¿La herramienta valida mis endpoints de API reales? No. El validador verifica que su archivo de spec sea estructuralmente correcto según el esquema OpenAPI. No realiza ninguna solicitud HTTP a los servidores o rutas listados en su spec.

¿Por qué mi spec falla aquí pero funciona en Swagger UI? Swagger UI renderiza specs con cierta tolerancia a errores. Este validador aplica validación estricta de esquema, que detectará problemas que Swagger UI ignora silenciosamente. Ambos comportamientos son por diseño — esta herramienta detecta problemas de calidad de la spec temprano, antes de que causen problemas en consumidores más estrictos como los generadores de SDK.

¿Qué significa "operationId required for SDK generation"? Los generadores de SDK como OpenAPI Generator y Kiota nombran los métodos generados según los valores de operationId. Sin ellos, los generadores recurren a construir nombres a partir del método HTTP y la ruta (ej., getApiV1UsersUserIdOrdersOrderId). Agregar valores operationId concisos y únicos a cada operación produce código de cliente generado mucho más limpio.

¿Hay falsos positivos en las advertencias? Las tres verificaciones de advertencias son conservadoras. La verificación de info.description se activa solo cuando el campo está ausente o vacío. La verificación de descripción de operación cuenta solo operaciones a las que les falta tanto description como summary — tener cualquiera suprime la advertencia para esa operación. La verificación de operationId es estricta: se cuenta cada operación que carece de uno.

¿Puedo validar un archivo de spec en lugar de pegarlo? La herramienta acepta solo texto pegado — no hay botón de carga de archivos. Abra su archivo de spec en un editor de texto, seleccione todo y pegue el contenido en el área de texto.

¿El panel de historial guarda el contenido de mi spec? Sí. Cuando valida una spec exitosamente, la herramienta guarda una entrada en el historial IndexedDB de su navegador (función de supporter) que contiene la spec de entrada y el resumen de validación. El historial es local en su navegador y nunca se sincroniza con un servidor.

¿Qué pasa si pego una spec vacía? El botón Validate está deshabilitado cuando el área de texto está vacía (disabled={!input.trim()}). Debe ingresar al menos un carácter que no sea espacio en blanco antes de que el botón se vuelva clickeable.

Herramientas relacionadas

• Próximamente: Generador de Mock de API — genere datos de respuesta mock desde su spec validada para usar en desarrollo frontend.
• Próximamente: Suite de Diseño de API — diseñe e itere sobre la estructura de la API antes de exportar al formato OpenAPI.
• Formateador JSON — formatee y valide la estructura JSON de su spec antes de pegarla en el validador.

Pruebe el Validador OpenAPI ahora: Validador OpenAPI