Fundamentos de API

La función de documentación API de Document360 te ofrece una solución completa y completa para publicar, gestionar y probar referencias de 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 pulida e interactiva para desarrolladores sin requerir herramientas personalizadas ni formato manual.

La experiencia del lector

Cuando publicas una referencia de API, los desarrolladores acaban en una página interactiva de tres paneles — no en un documento estático. Entender este diseño 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 una. Los lectores filtran por nombre para saltar rápidamente a un endpoint.
• 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, ). 500Los 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 el error en su integración.

Pruébalo

Prueba Convierte la referencia de algo que los lectores han leído en algo que pueden ejecutar. 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 Probar endpoints con Prueba Lo Hace 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 Try It 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 Uso de variables en la consola Pruébalo.

Eddy AI

Eddy AI está integrado en la referencia para que los lectores puedan hacer preguntas sobre un endpoint: cómo funciona, cómo autenticarse, 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 devuelven y cómo funciona la autenticación. A diferencia de los artículos de la base de conocimiento general, la documentación de la 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. La documentación clara reduce la incorporación de días a horas. Los desarrolladores pasan menos tiempo adivinando y más tiempo construyendo.
• Reduce la carga de soporte. 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

En Document360, la documentación de la API está en un espacio de trabajo dedicado de la API 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, consulta la documentación para desarrolladores de Document360.

Formatos de especificaciones soportados

Document360 soporta los siguientes formatos de especificaciones:

• OpenAPI 3.2
• OpenAPI 3.1 (incluye soporte para webhook)
• OpenAPI 3.0
• OpenAPI 2.0 (anteriormente Swagger)
• Colecciones del Cartero

Los archivos pueden subirse como JSON, YAML o YML.

OpenAPI 3.2 añade soporte para:

• El método HTTP QUERY para operaciones de lectura que requieren un cuerpo de solicitud
• Categorías anidadas generadas automáticamente a partir de jerarquías de etiquetas
• El flujo de Autorización de Dispositivo (RFC 8628) como una opción adicional de OAuth2
• Esquemas de respuesta en streaming para eventos enviados por servidor y líneas JSON
• Servidores nombrados, valores de ejemplo más ricos y URIs canónicos de documentos ($self)

Webhooks en OpenAPI 3.1

Document360 soporta webhooks definidos en OpenAPI 3.1. Los webhooks aparecen con un icono de evento en tu referencia 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 ejemplo. Pruébalo! 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, consulta 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