La función de documentación de la 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.
¿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.
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.
La función Pruébalo! en Document360 te permite probar los endpoints de la API directamente en la base de conocimientos. La consola interactiva permite a los desarrolladores introducir los parámetros necesarios y ejecutar llamadas a la API, obteniendo respuestas en tiempo real, sin salir de la documentación ni escribir código.
La sección Pruébalo! soporta múltiples esquemas de seguridad simultáneamente, permitiendo a los usuarios probar de forma más eficaz los endpoints que requieren métodos de autenticación combinados.
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.
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:
- Redireccionar URI - Configura esto en tu proveedor OAuth al formato
domain/oauth. Por ejemplo:https://apidocs.document360.com/oauth. - 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
¿En qué se diferencia la documentación de la API de la documentación normal?
La documentación de la API está diseñada específicamente para explicar endpoints, autenticación e integraciones. Es independiente de los artículos estándar de la base de conocimientos y útil para contenido orientado a desarrolladores.
¿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áles son los formatos de archivo de especificación compatibles?
Puedes subir tu archivo de especificación como un archivo URL, JSON, YAML o YML . Document360 es compatible con las especificaciones OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 y Postman.
¿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.
Vídeos relacionados
Descubre nuestra documentación moderna de API en Document360
Endpoints de API de prueba directamente desde la documentación con Try It!
Información adicional
Lee nuestro blog sobre - Presentando la documentación de API: Mejora tu experiencia API