Este visor y validador de OpenAPI lee un documento OpenAPI 3.0, 3.1 o Swagger 2.0 en YAML o JSON y lo muestra como documentación de API navegable: cada endpoint agrupado por tag, con sus parámetros, cuerpo de solicitud, respuestas y esquemas, además de un comando cURL listo para ejecutar. Pega la especificación o abre el archivo; no se sube nada, así que las API internas y sin publicar siguen siendo privadas.
El validador ejecuta 23 comprobaciones estructurales tomadas de las especificaciones, todas enumeradas en la página: que existan info y paths, respuestas con descripción y códigos de estado válidos, cada {parameter} de una ruta declarado como parámetro de ruta obligatorio, operationId únicos, $ref que se resuelven y requisitos de seguridad que nombran un esquema definido. Son los errores que rompen los generadores de código y las herramientas de documentación. No es una validación completa contra el JSON Schema oficial de la especificación, así que una especificación que pasa aquí puede tener todavía, por ejemplo, una palabra clave de esquema mal escrita. Los $ref externos a otros archivos se enumeran, pero no se descargan.
Cómo usarla
- Pega tu openapi.yaml, openapi.json o swagger.json, o abre el archivo. Para empezar se carga una API de ejemplo.
- Lee la línea de estado y la lista de Validación. Cada problema indica la regla y dónde está (por ejemplo paths./pets/{id}.get).
- Consulta la documentación: las operaciones se agrupan por tag; haz clic en una para ver sus parámetros, cuerpo de solicitud, respuestas y esquemas.
- Filtra por ruta, resumen u operationId para encontrar un endpoint en una especificación grande.
- Copia el ejemplo cURL de una operación y sustituye el marcador <TOKEN> o <API_KEY> por tus credenciales.
Preguntas frecuentes
¿Cómo veo un archivo Swagger u OpenAPI?
Pega el YAML o el JSON en el cuadro o abre el archivo. El visor detecta la versión (swagger: "2.0" u openapi: 3.0.x / 3.1.x), enumera los endpoints agrupados por tag y te permite desplegar cada uno para ver sus parámetros, cuerpo de solicitud, respuestas y esquemas resueltos. Funciona sin conexión una vez cargada la página.
¿Qué comprueba el validador de OpenAPI?
Reglas estructurales de la especificación: un campo de versión compatible; info con title y version; rutas que empiezan por /; operaciones con responses no vacías que tienen descripción y códigos de estado válidos; parámetros de la plantilla de ruta declarados y obligatorios; parámetros con name, un in válido y un schema; sin parámetros ni operationId duplicados; cuerpos de solicitud con content; $ref que se resuelven; y requisitos de seguridad que nombran esquemas definidos. La lista completa está en la página, en «Qué se comprueba». No valida cada palabra clave de esquema contra el JSON Schema oficial.
¿Por qué un parámetro de ruta sin declarar es un error?
La especificación exige que cada {name} de una plantilla de ruta tenga un parámetro correspondiente con in: path y required: true, a nivel de ruta o de operación. Algunos validadores que solo comprueban el documento contra el JSON Schema aceptan que falte, pero luego los generadores de código producen una función sin argumento para él, y las herramientas de documentación muestran un endpoint al que no se puede llamar correctamente.
¿Puede leer OpenAPI 3.1 y Swagger 2.0?
Sí. Los parámetros body y formData de Swagger 2.0 se muestran como cuerpo de solicitud, con produces y consumes como tipos de medio, así que las tres versiones se leen igual. Se respetan las diferencias de OpenAPI 3.1: paths es opcional cuando hay components o webhooks, responses es opcional (aquí es un aviso) y type: [string, "null"] se muestra como nullable.
¿Carga archivos $ref externos?
No. Un $ref a otro archivo o URL (por ejemplo ./schemas/user.yaml) aparece como aviso y se muestra sin resolver, porque la página no puede leer archivos que no has abierto y no descarga URL por su cuenta. Agrupa primero una especificación de varios archivos en un solo documento, por ejemplo con redocly bundle o swagger-cli bundle.
¿Se sube mi especificación de API?
No. El análisis, la validación y la representación se hacen en tu navegador. La especificación nunca se envía a ningún sitio.
OpenAPI 3.x y Swagger 2.0: qué cambió
• Campo de versión: swagger: "2.0" pasó a ser openapi: 3.0.x, y después 3.1.x.
• Servidores: 2.0 tiene host, basePath y schemes; 3.x tiene una lista servers con variables.
• Cuerpos de solicitud: 2.0 usa un parámetro con in: body (o formData); 3.x tiene requestBody con content por tipo de medio.
• Partes reutilizables: en 2.0, definitions, parameters y responses en el nivel superior; 3.x las pone dentro de components, junto con securitySchemes, requestBodies y examples.
• 3.1 alinea los esquemas con JSON Schema 2020-12: type puede ser una lista (["string", "null"] en lugar de nullable: true), examples es un array y se añaden los webhooks.
Los errores que más a menudo rompen las herramientas de API
• Parámetros de ruta que no se declaran o se declaran sin required: true.
• Un $ref con una errata (#/components/schema/User en lugar de schemas), que deja vacía parte de la documentación.
• operationId duplicados, que hacen fallar a los generadores de código o sobrescriben métodos.
• Respuestas sin description (es obligatoria, aunque solo sea "OK").
• Un requisito de seguridad que nombra un esquema no definido, así que el cliente generado no tiene forma de autenticarse.
