Visor Básico de Documentación API (JSON)

Guía de Uso del Visor de Documentación API

1. Carga tu Archivo de Especificación API:
   • En la barra lateral izquierda, haz clic en el botón "Seleccionar archivo" (o el área designada) bajo "Cargar Especificación API (JSON)".
   • Selecciona un archivo .json de tu computadora que contenga una especificación API válida (por ejemplo, un archivo OpenAPI 2.0 o 3.x, o un archivo Swagger 2.0).
2. Explora la Información General (si está disponible):
   • Una vez cargado el archivo, si la especificación contiene una sección info, verás el título, versión y una breve descripción de la API en la parte superior de la barra lateral.
3. Navega por los Endpoints:
   • La lista de "Endpoints" en la barra lateral se poblará con todos los paths (rutas URL) y los métodos HTTP (GET, POST, PUT, DELETE, etc.) definidos en tu especificación.
   • Cada método se muestra con un color distintivo para fácil identificación.
   • Haz clic en cualquier endpoint de la lista para ver sus detalles en el panel principal a la derecha. El endpoint seleccionado se resaltará.
4. Revisa los Detalles del Endpoint Seleccionado:
   • Método y Path: Se muestra claramente el método HTTP y la ruta del endpoint.
   • Resumen y Descripción: Si están definidos en la especificación, verás un resumen conciso y una descripción más detallada de la funcionalidad del endpoint.
   • Parámetros: Si el endpoint requiere o acepta parámetros (en el path, query string, cabeceras o cookies), se listarán en una tabla con su nombre, ubicación (in), descripción, si son requeridos, y su tipo o esquema.
   • Cuerpo de la Petición (Request Body): Si el endpoint espera un cuerpo en la petición (común para POST, PUT, PATCH), se mostrará su descripción, si es requerido, y el esquema o un ejemplo del cuerpo esperado para los tipos de contenido soportados (ej. application/json).
   • Respuestas Posibles: Se listarán las diferentes respuestas que el endpoint puede devolver, agrupadas por código de estado HTTP (ej. 200 OK, 404 Not Found, 500 Server Error). Para cada respuesta, se mostrará su descripción y, si está definido, el esquema o un ejemplo del cuerpo de la respuesta para los tipos de contenido soportados. Los ejemplos JSON se mostrarán formateados.
5. Modo Pantalla Completa: Utiliza el botón "Pantalla Completa" (o la tecla 'F') para visualizar la documentación API en un espacio de trabajo más amplio, ideal para especificaciones extensas.
6. Errores: Si el archivo JSON cargado no es válido o no sigue un formato de especificación API reconocible, se mostrará un mensaje de error.

Características Clave del Visor API

• Carga de Archivos JSON: Permite cargar archivos de especificación API locales en formato JSON (compatible con OpenAPI/Swagger).
• Visualización Estructurada: Presenta la información de la API de forma organizada, con una barra lateral para navegar por los endpoints y un panel principal para los detalles.
• Información General de la API: Muestra título, versión y descripción de la API si están presentes en la especificación.
• Listado Detallado de Endpoints: Enumera todos los paths y métodos HTTP, con indicadores visuales para cada método.
• Desglose Completo de Endpoints: Para cada endpoint, se detallan:
  • Resumen y descripción.
  • Parámetros (nombre, ubicación, descripción, requerido, tipo/schema).
  • Cuerpo de la petición (descripción, requerido, esquema/ejemplo por tipo de contenido).
  • Respuestas posibles (código de estado, descripción, esquema/ejemplo por tipo de contenido).
• Formateo de Ejemplos JSON: Los esquemas o ejemplos JSON en las peticiones y respuestas se muestran indentados para facilitar su lectura.
• Manejo Básico de Referencias $ref: Intenta resolver referencias internas simples dentro de #/components/schemas/ para mostrar los esquemas referenciados.
• Interfaz Limpia y Responsiva: Diseño intuitivo que facilita la exploración de la documentación API.
• Modo Pantalla Completa: Ofrece una vista expandida para una navegación y lectura más cómoda de la documentación.
• Procesamiento en el Navegador: El archivo JSON se procesa localmente; no se envía a ningún servidor, garantizando la privacidad de tus especificaciones.
• Herramienta Gratuita Optikit: Una solución accesible para visualizar documentación API JSON sin costo.

Preguntas Frecuentes sobre el Visor de Documentación API

¿Qué tipo de archivos JSON puedo cargar en este visor de API?

Esta herramienta está diseñada principalmente para visualizar archivos JSON que siguen la especificación OpenAPI (versiones 2.0 -antes Swagger- y 3.x). Si tienes un archivo swagger.json o openapi.json, deberías poder cargarlo y explorarlo. Es un visor de OpenAPI online básico.

¿Cómo me ayuda esta herramienta a entender una API desconocida?

Al cargar la especificación, obtendrás una lista clara de todos los endpoints disponibles, los métodos HTTP que aceptan, los parámetros necesarios y las respuestas que puedes esperar. Esto te da una hoja de ruta para interactuar con la API y entender su funcionalidad sin tener que leer el JSON crudo. Es una herramienta para explorar APIs.

¿El visor muestra ejemplos de peticiones y respuestas?

Sí, si la especificación API incluye ejemplos (example o examples) para los cuerpos de petición o respuesta, o para los esquemas (schema), la herramienta intentará mostrarlos. Los ejemplos JSON se formatean para facilitar su lectura. Es útil para ver la documentación de API JSON de forma práctica.

¿Qué pasa si mi archivo de especificación API es muy grande?

La herramienta procesa el archivo en tu navegador. Para archivos JSON extremadamente grandes (muchos megabytes), el rendimiento podría verse afectado durante la carga y el parseo. Sin embargo, para la mayoría de las especificaciones API comunes, debería funcionar sin problemas. Optikit ofrece esta herramienta gratuita para uso general.

¿Soporta la herramienta referencias internas ($ref) en el archivo OpenAPI/Swagger?

Sí, el visor tiene un soporte básico para resolver referencias internas que apuntan a esquemas definidos dentro de la sección #/components/schemas/ de tu archivo OpenAPI 3.x (o #/definitions/ para Swagger 2.0, aunque el parseo aquí es más genérico). Esto permite mostrar la estructura de objetos complejos referenciados. Para referencias más complejas o externas, la resolución podría ser limitada.

¿Mis archivos de especificación API se guardan en algún sitio o son privados?

Tus archivos JSON se cargan y procesan enteramente en tu navegador. No se suben ni se guardan en los servidores de Optikit. La privacidad de tu documentación API está asegurada al usar esta herramienta inteligente de Optikit.

¿Puedo usar esto como un reemplazo completo de Swagger UI o Redoc?

Este es un visor básico, ideal para una exploración rápida y sencilla de archivos JSON de especificación API. Herramientas como Swagger UI o Redoc ofrecen funcionalidades más avanzadas, como la ejecución de peticiones "Pruébalo" o una renderización más rica de Markdown. Nuestro visor de API online se enfoca en la simplicidad y la visualización directa desde un archivo JSON.

¿Cómo me ayuda el modo "Pantalla Completa" a visualizar la documentación?

El modo "Pantalla Completa" (botón o tecla 'F') maximiza el área de visualización de la herramienta, eliminando distracciones del navegador. Esto es especialmente útil cuando estás examinando especificaciones API largas o complejas, permitiéndote ver más información de los endpoints y sus detalles a la vez y concentrarte en la exploración de la documentación API.

¿Qué hago si mi archivo JSON no se carga o muestra un error?

Primero, asegúrate de que el archivo es un JSON válido. Puedes usar un validador JSON online para comprobarlo. Segundo, verifica que el JSON sigue una estructura similar a la de OpenAPI/Swagger, especialmente con un objeto paths que define los endpoints. Si el error persiste, el archivo podría ser demasiado complejo para este visor básico o tener una estructura no estándar. Esta herramienta online gratis busca simplicidad.

¿Puedo ver los tipos de datos de los parámetros y cuerpos de respuesta?

Sí. Para los parámetros, la columna "Tipo/Schema" indicará el tipo de dato (ej. string, integer) o una referencia a un schema si está definido. Para los cuerpos de petición y respuesta, si se proporciona un schema, la herramienta intentará mostrarlo o generar un ejemplo basado en él, lo que te dará una idea clara de la estructura y los tipos de datos esperados/devueltos por la API.