La función de documentación API de Document360 te ofrece una solución completa y completa para publicar, gestionar y probar referencias de la API. Ya seas una startup que lanza su primera API pública o una empresa que mantiene decenas de microservicios internos, Document360 convierte tu especificación OpenAPI en una documentación para desarrolladores pulida e interactiva sin requerir herramientas personalizadas ni formato manual.
La experiencia del lector
Cuando publicas una referencia de API, los desarrolladores llegan a una página interactiva de tres paneles — no a un documento estático. Entender esta estructura te ayuda a imaginar lo que realmente ven tus lectores y te dirige al artículo que explica cada parte en profundidad.
- Izquierda - árbol de navegación. Cada endpoint en tu especificación, agrupado por etiqueta en categorías y subcategorías, con una etiqueta de método (GET, POST, PUT, PATCH, DELETE) junto a cada uno. Los lectores filtran por nombre para saltar rápidamente a un punto final.
- Centro - documentación. La descripción del endpoint, los parámetros de ruta y consulta, el esquema del cuerpo de la solicitud y los requisitos de autenticación, todo generado a partir de tu especificación.
- Correcto - paneles de código y respuesta. Ejemplos de solicitudes listas para usar y respuestas de ejemplo, junto con la documentación.
Panel de códigos
El panel de códigos muestra una muestra de solicitud lista para copiar para el endpoint, y los lectores pueden cambiar el idioma para que coincida con su pila. Hay seis idiomas disponibles:
- cURL
- Shell
- Python
- Java
- JavaScript
- C#
Cada muestra se actualiza para reflejar la ruta real del endpoint, los parámetros y la autenticación, de modo que el lector pueda copiarla directamente en su propio entorno.
Panel de respuesta
El panel de Respuestas muestra respuestas de ejemplo para el endpoint, organizadas por código de estado (por ejemplo, respuestas de éxito y error como 200, 401, 403, 404, 422, 429, , 500). Los lectores seleccionan un código de estado para ver la forma de la respuesta que deben esperar en cada caso, lo que facilita gestionar tanto el éxito como los errores en su integración.
Pruébalo
Try It convierte la referencia de algo que los lectores leen en algo que pueden publicar. Abre una consola interactiva en línea en cualquier punto final, para que los desarrolladores puedan enviar una solicitud real y ver la respuesta en tiempo real — estado, tiempo, encabezados y cuerpo — sin salir de la página ni escribir código. Consulta Testing endpoints con Pruébalo! para la guía completa.
Autenticación
Los lectores proporcionan las credenciales directamente en la consola Try It usando el esquema que defina tu API — clave API, HTTP Basic, HTTP Bearer, OAuth 2.0 o OpenID Connect. Try It lee los esquemas de tu especificación y muestra los campos correctos para cada uno. Consulta Autorizar solicitudes en la consola de Prueba para detalles sobre cada método.
Variables
Las variables permiten a los lectores almacenar un valor una vez, como un ID o un token, y reutilizarlo en cada extremo de la referencia con un {{placeholder}}. Esto evita volver a escribir valores comunes a medida que se mueven de un extremo a otro. Consulta Usar variables en la consola de Pruébalo.
Eddy AI
Eddy AI está integrada en la referencia para que los lectores puedan hacer preguntas sobre un endpoint: cómo funciona, cómo autenticar, o para obtener un ejemplo de código en un lenguaje específico y obtener respuestas sin salir de la página. Consulta Usar Eddy AI en la referencia de la API.
¿Qué es la documentación de la API y por qué importa?
La documentación de la API es la referencia técnica que indica a los desarrolladores exactamente cómo interactuar con tu API: qué endpoints existen, qué parámetros aceptan, qué respuestas demuestran y cómo funciona la autenticación. A diferencia de los artículos de la base de conocimientos generales, la documentación API sigue un formato estricto y estructurado derivado de un archivo de especificación legible por máquina.
Por qué es importante:
- Reduce el tiempo de integración. Los documentos claros reducen la incorporación de días a horas. Los desarrolladores pasan menos tiempo adivinando y más tiempo construyendo.
- Reduce la carga de apoyo. Cuando los documentos responden a las preguntas "¿cómo me autentico?" y "¿qué significa un 422?", tu equipo recibe menos tickets.
- Genera confianza entre los desarrolladores. La documentación de la API incompleta o desactualizada indica un producto poco fiable. La documentación de alta calidad es una señal directa de la calidad del producto.
- Permite el autoservicio. Socios externos, clientes y desarrolladores externos pueden integrarse sin necesidad de que tu equipo te acompañe.
Documentación de API frente a documentación regular
| Aspecto | Documentación de la API | Documentación regular |
|---|---|---|
| Público principal | Desarrolladores e integradores técnicos | Usuarios finales, equipos internos |
| Estructura | Impulsado por un archivo de especificaciones (OpenAPI, Postman) | Artículos escritos manualmente |
| Tipo de contenido | Endpoints, parámetros, esquemas, métodos de autenticación | Guías, tutoriales, artículos conceptuales |
| Interactividad | Pruebas en vivo a través de Try It! | Lectura estática |
| Versión | Vinculado a versiones específicas de la API | Gestionado editorialmente |
| Generación automática | Sí, del archivo de especificaciones | No |
En Document360, la documentación de la API se encuentra en un espacio de trabajo dedicado que está separado de tu base de conocimiento estándar. Esto permite diferentes controles de acceso, enrutamiento y marca para tu contenido orientado a desarrolladores. Para una referencia completa de todos los endpoints y esquemas disponibles, consulte la documentación de desarrollador de Document360.
Formatos de especificaciones soportados
Document360 soporta los siguientes formatos de especificaciones:
- OpenAPI 2.0 (anteriormente Swagger)
- OpenAPI 3.0
- OpenAPI 3.1 (incluye soporte para webhook)
- Colecciones del Cartero
Los archivos pueden subirse como JSON, YAML o YML.
Si empiezas de cero, usa OpenAPI 3.1. Es el estándar actual, soporta webhooks de forma nativa y tiene el ecosistema de herramientas más rico. Si estás migrando desde una configuración existente de Swagger 2.0, Document360 lo acepta tal cual mientras actualizas de forma incremental.
Webhooks en OpenAPI 3.1
Document360 soporta webhooks definidos en OpenAPI 3.1. Los Webhooks aparecen con un icono de evento en la referencia de tu API e incluyen una sección de payload basada en tu esquema. Si no se proporciona ningún ejemplo, Document360 muestra un ejemplo por defecto y una carga útil de muestra. Try It! no está disponible para webhooks. Los Webhooks son compatibles para subidas de archivos, importaciones de URL y flujos CI/CD.
Técnicas de autorización
Al interactuar con una API, es importante asegurarse de que solo los usuarios autorizados puedan acceder a ciertos datos o realizar acciones específicas. Document360 soporta los siguientes métodos de autorización:
- Autenticación básica - Requiere un nombre de usuario y una contraseña que se transmitan en la solicitud.
- Token portador - Se autentica con un token generado tras iniciar sesión.
- Clave API - Utiliza una clave única, pasada en los encabezados de la solicitud, para autenticación.
- OAuth2 - Protege las APIs a través de varios flujos: Código de Autorización, PKCE, Credenciales del Cliente e Implícito.
- OpenID Connect - Extiende OAuth2 añadiendo verificación de identidad de usuario.
Para autenticar las solicitudes a la API de Cliente de Document360, necesitarás un token de API. Para más información, consulte el artículo sobre tokens API .
Para hacer tu primera solicitud de API autenticada usando Swagger, Postman o curl, consulta Making your first request.
OAuth2 y OpenID Connect: configuración adicional
Al trabajar con APIs que usan OAuth2 u OpenID Connect, se requieren dos ajustes para que Try It! funcione correctamente:
- URI de redirección - Configura esto en tu proveedor OAuth a la URL de callback OAuth de la referencia de la API:
https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html. - Renovación silenciosa - Document360 actualiza automáticamente el token de autorización en segundo plano durante las sesiones activas de Prueba!, por lo que los usuarios no necesitan volver a autenticarse manualmente.
Preguntas frecuentes
¿Qué es una referencia de API?
Una referencia de API es un recurso documental que proporciona información completa sobre las funciones, clases, métodos, parámetros, tipos de retorno y otros componentes de una API. Es una guía o manual para desarrolladores que desean integrar o utilizar la API en sus aplicaciones.
¿Cuántas referencias API puedo crear?
Dentro de cada espacio de trabajo de API, puedes crear un máximo de 3 referencias API.
¿Cuál es el orden predeterminado de las categorías al subir un archivo de especificación de OpenAPI?
Las categorías en Document360 se crean en función del orden de etiquetas definido en tu archivo de especificaciones. Por ejemplo, si tu especificación define etiquetas en el orden Mascota, Tienda, Usuario — las categorías aparecerán en ese mismo orden.
La opción "¡Pruébalo!" no está disponible en la página de la base de conocimientos. ¿Cuál podría ser la razón?
Si la función Pruébalo! , asegúrate de que tanto la variable del servidor como la URL del servidor estén correctamente definidas en tu archivo de especificación de la API. Sin estos, la función no funcionará.
¿Se pueden modificar los valores desplegables de referencia de la API a través de la interfaz?
No. Los cambios en los elementos de referencia de la API, como los valores desplegables, solo pueden realizarse a través del archivo de especificación de OpenAPI. Actualmente no se permite modificar estos valores a través de la interfaz.