Visor de OpenAPI / Swagger
Pega, sube o carga una especificación OpenAPI (Swagger) para explorarla como documentación de API limpia y con buscador, ábrela en Swagger UI y consulta los errores de validación con su ubicación exacta. Funciona con OpenAPI 2.0, 3.0 y 3.1 en JSON o YAML, por completo en tu navegador.
Última actualización:
Swagger UI se carga desde una CDN pública la primera vez que abres esta pestaña. "Try it out" envía peticiones desde tu navegador directamente a los servidores de la API indicados en la especificación.
Cómo usar Visor de OpenAPI / Swagger
- Añade tu especificación: pega JSON o YAML en el editor, abre un archivo openapi.yaml / swagger.json, arrástralo al recuadro o carga una URL pública.
- Haz clic en Ver documentación (o simplemente sigue escribiendo: la vista se actualiza automáticamente).
- Explora los endpoints: busca por ruta o resumen, filtra por método HTTP y haz clic en una operación para ver sus parámetros, el cuerpo de la petición, las respuestas y ejemplos de datos.
- Corrige los problemas: la pestaña Problemas enumera los errores y advertencias con la ruta JSON donde aparecen.
- Abre Swagger UI para la vista interactiva clásica, o descarga la especificación convertida a JSON o YAML.
Estructura de un documento OpenAPI
| Sección | OpenAPI 3.x | Swagger 2.0 |
|---|---|---|
| Campo de versión | openapi: 3.0.3 o 3.1.0 | swagger: "2.0" |
| Detalles de la API | info (title y version obligatorios) | info |
| URL base | servers[].url | schemes + host + basePath |
| Endpoints | paths (opcional en 3.1 con webhooks) | paths |
| Cuerpo de la petición | requestBody.content por tipo de medio | un parámetro con in: body |
| Esquemas reutilizables | components.schemas | definitions |
| Autenticación | components.securitySchemes | securityDefinitions |
| Esquema de respuesta | responses.200.content['application/json'].schema | responses.200.schema |
Errores de validación más comunes
- Parámetro de ruta no definido: cada
{id}de una ruta necesita un parámetro correspondiente conin: pathyrequired: true, ya sea en la operación o en el path item. - $ref roto: una errata en
#/components/schemas/Name, o un esquema al que se cambió el nombre. Las referencias distinguen mayúsculas y minúsculas. - Respuesta sin descripción:
descriptiones obligatorio en todos los objetos de respuesta en 2.0 y 3.x, aunque sea una cadena vacía. - Versión o códigos de estado sin comillas en YAML: escribe
"200"yversion: "1.0"entre comillas para que YAML no los convierta en números. - operationId duplicado: los generadores de código lo usan para los nombres de los métodos, así que cada uno debe ser único.
- Arrays sin items:
type: arraynecesita un esquemaitems.
OpenAPI 3.0 frente a 3.1
OpenAPI 3.1 alinea los esquemas con JSON Schema 2020-12: type puede ser un array como [string, "null"] en lugar de nullable: true, examples es un array, exclusiveMinimum es un número y un documento puede contener solo webhooks o components sin paths. Este visor acepta ambos estilos y aplica las reglas correspondientes a la versión declarada en el documento.
Preguntas frecuentes
¿Qué diferencia hay entre Swagger y OpenAPI?
Swagger 2.0 pasó a llamarse OpenAPI Specification cuando se trasladó a la OpenAPI Initiative en 2016. OpenAPI 3.0 (2017) y 3.1 (2021) son las versiones más recientes. Swagger se refiere ahora a las herramientas de SmartBear, como Swagger UI y Swagger Editor, que trabajan con archivos OpenAPI.
¿Qué versiones admite este visor?
Lee documentos Swagger/OpenAPI 2.0 (swagger: "2.0") y documentos OpenAPI 3.0.x y 3.1.x (openapi: "3.x.x"), escritos en JSON o YAML.
¿Qué comprueba el validador?
Campos obligatorios como info.title, info.version, paths y responses; claves y parámetros de ruta; ubicaciones de los parámetros; operationId duplicados; punteros $ref locales rotos; esquemas de seguridad desconocidos; tipos de esquema no válidos y arrays sin items. Es una comprobación estructural práctica, no una validación completa con JSON Schema de la especificación.
¿Se sube mi especificación de API?
No. La especificación se analiza y se muestra en tu navegador. Solo la vista opcional de Swagger UI descarga la biblioteca Swagger UI desde una CDN pública, y el cargador de URL descarga la dirección que introduces. No se envía nada a FreeToolCabin.
¿Por qué falla la carga desde una URL?
El navegador solo puede leer una especificación de otro sitio si ese servidor permite peticiones de origen cruzado (CORS). Si la carga falla, abre la URL en una pestaña nueva, guarda el archivo y ábrelo aquí, o pega su contenido.
¿Se admiten archivos $ref externos?
Las referencias dentro del mismo documento (que empiezan por #/) se resuelven. Las referencias a otros archivos o URL se muestran como advertencias y no se siguen, porque el visor solo tiene el documento que le proporcionas.
¿Se prueban todas las herramientas de FreeToolCabin para comprobar su calidad y precisión?
Sí. Cada herramienta del sitio pasa pruebas automáticas en navegadores reales para comprobar que el resultado es correcto y que no hay errores. Si encuentras un fallo o tienes una sugerencia, escríbenos a [email protected] y lo revisaremos.