Introducción a la documentación de la API

Documentación de la API de soporte de planes

La función de documentación API de Document360 proporciona una solución completa para crear y gestionar referencias de API. Esta función le permite generar documentación de API de alta calidad que ayuda a los usuarios a comprender y trabajar con sus API de manera efectiva. Puede generar esta documentación cargando el archivo de especificación de API desde una dirección URL, un archivo JSON/YAML/YML o mediante la integración con un flujo de CI/CD.

Además, la función ¡Pruébelo! de Document360 le permite probar los extremos de la API directamente en el Knowledge base site. La consola interactiva en el sitio de la base de conocimientos permite a los desarrolladores ingresar los parámetros necesarios y ejecutar llamadas a la API, obteniendo respuestas en tiempo real. Esta característica es útil para solucionar problemas y comprender cómo se comporta una API sin salir de la documentación ni escribir ningún código.

Incorporación de la documentación de la API

Al registrarse en Document360, los usuarios eligen su caso de uso principal en el paso 1 del flujo de incorporación. Para los usuarios que deseen crear documentación de API, Document360 proporciona una experiencia de incorporación optimizada. Si selecciona la documentación de la API como caso de uso, se le redirigirá al flujo de configuración de la API, donde puede crear referencias de API utilizando las opciones disponibles.

En el paso 2 del flujo de incorporación, tendrá tres opciones para crear una referencia de API:

• Cargar archivo de API: admite archivos JSON/YAML/YML (colecciones OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 y Postman).

• Crear a partir de URL: Obtiene automáticamente la especificación de la API de la URL alojada.

• Pruebe el archivo de API de muestra de la tienda de mascotas: si no tiene un archivo de API listo, puede utilizar el archivo de muestra (API de la tienda de mascotas) que ofrece Document360 para rellenar su espacio de trabajo.

Carga de un archivo de definición de API

Para crear una referencia de API a partir de un archivo de definición de API, seleccione el botón de opción Cargar archivo de API. A continuación, haga clic en Cargar desde mi dispositivo o arrastre y suelte el archivo de especificaciones de la API desde su dispositivo.

NOTA

Los formatos de archivo admitidos para el archivo de definición de API son JSON, YAML o YML.

El sistema analizará el archivo y generará la referencia de la API automáticamente.

• Sise detectan alertas/advertencias en el archivo cargado, se mostrará una descripción general de alto nivel durante la incorporación. Puede ver detalles detallados en el portal de la base de conocimientos, en la sección de registros, en Más opciones dentro de las referencias de API.

• Si se detecta algún error en el archivo cargado (por ejemplo, formato de archivo no compatible), reemplace el archivo cargado por un archivo alternativo.

Introducción de una URL de documentación de API

Para crear una referencia de API a partir de una URL de documentación de API, seleccione el botón de opción Crear a partir de URL . A continuación, introduzca la URL del archivo OpenAPI en el campo URL de la definición de API . Document360 recuperará y procesará la estructura de la API. Al igual que la carga de archivos,

• Si se detecta alguna alerta/advertencia, puede verla en el portal de la base de conocimientos en la sección de registros en Más opciones dentro de la referencia de API.

• Si se detecta algún error (por ejemplo, URL no válida), introduzca la URL válida para el archivo OpenAPI.

Omitir la configuración de la API

Si eliges la opción Probar archivo de API de tienda de mascotas de muestra ,

• Document360 creará automáticamente una referencia de API de ejemplo (API de tienda de mascotas).

• Estará disponible en modo borrador. Puede revisar los puntos de conexión antes de publicar o cargar el archivo de especificaciones y publicarlo más tarde.

Personaliza tu base de conocimientos

En el paso 3, puedes introducir la URL de tu sitio web preferido. Si desea omitir este paso, el dominio será el vinculado a su correo electrónico de registro de forma predeterminada.

Directrices de la marca

En el paso 4, el nombre del proyecto, el idioma predeterminado, el logotipo de la marca y los colores de la marca se establecen automáticamente en función de la URL proporcionada. Sin embargo, puede editar estos campos si es necesario. La configuración de idioma de su navegador determina el idioma predeterminado. El inglés se seleccionará de forma predeterminada si otros idiomas no son compatibles con el idioma de su navegador.

NOTA

• Si elige español o portugués de Brasil como idioma predeterminado, el idioma del portal se establecerá en español o portugués de Brasil. De lo contrario, el inglés será el idioma predeterminado.

• El logotipo de la marca y los colores primarios/secundarios se extraen de su sitio web. Si decide Omitir este paso, el nombre del proyecto se derivará de su correo electrónico de registro y se aplicarán el logotipo y los colores predeterminados de Document360.

Establecer la privacidad de la documentación

En el paso 5, puedes elegir la configuración de privacidad deseada para tu sitio:

• Privado: restrinja el acceso a la base de conocimientos para que solo las cuentas de equipo puedan ver e interactuar con el contenido, manteniéndolo seguro e interno.

• Público: Hacer que la base de conocimientos sea accesible para todos, incluidos los usuarios externos, permitiendo el acceso abierto a todo el contenido.

• Mixto: combine el acceso privado y público permitiendo que algunas secciones de la base de conocimientos sean visibles para el público, mientras que otras secciones se restringen solo a las cuentas de equipo.

Por último, haga clic en Siguiente para completar el proceso de incorporación de la API.

Se le redirigirá al espacio de trabajo de documentación de la API, donde:

• Verá la referencia de API de la especificación de API que proporcionó durante la incorporación.

• Si no proporcionó una especificación de API, estará disponible en modo de borrador una referencia de API de ejemplo (API de tienda de mascotas).  

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. Esto se hace mediante técnicas de autorización, que controlan el acceso y los permisos. Document360 admite varios métodos de autorización para proteger su API, entre los que se incluyen:

• Autenticación básica: Requiere un nombre de usuario y una contraseña pasados en la solicitud.

• Token de portador: se autentica con un token generado después del inicio de sesión.

• Clave de API: utiliza una clave única, que se pasa en los encabezados de la solicitud, para la autenticación.

• OAuth2: protege las API a través de varios flujos, como código de autorización, PKCE, credenciales de cliente y flujos implícitos.

• OpenID Connect: amplía OAuth2 al agregar la verificación de identidad del usuario.

Consideraciones de autorización (OAuth2 y OpenID)

Al trabajar con API que usan OAuth2 u OpenID para la autorización, ciertas configuraciones son esenciales para una funcionalidad adecuada.

• URI de redireccionamiento: esta es la URL a la que se redirigirá al usuario después de completar un flujo de autorización. Asegúrese de establecer el URI en el formato: domain/oauth. Por ejemplo: https://apidocs.document360.com/oauth.

• Renovación silenciosa: la renovación silenciosa actualiza automáticamente el token de autorización en segundo plano, para que los usuarios no tengan que volver a autenticarse durante su sesión. Esto mantiene su sesión activa sin interrupción. Para evitar que la autorización caduque durante las sesiones en las que los usuarios interactúan con la función ¡Pruébelo! , Document360 renueva automáticamente el token de actualización en segundo plano. Esto garantiza que los usuarios no tengan que volver a autenticarse manualmente.

Adquisitivo

Tendrá acceso a 1 espacio de trabajo de API como parte de todos los planes de pago de Document360 (Professional, Business y Enterprise). Si desea comprar espacios de trabajo de API adicionales,

1. Vaya a Configuración() > portal de la base de conocimientos > Facturación > Mi plan.

2. Haz clic en Comprar complemento.

3. Agregue el número deseado de espacios de trabajo de documentación de API. Revise el costo del complemento y el monto adeudado.

4. Haga clic en Confirmar pago para continuar con el pago.

Solución de problemas

Problemas de acceso a la API

Error: Error 400: el acceso a la API está deshabilitado. Póngase en contacto con el administrador del proyecto.

Este error se produce cuando el acceso a la API pública está desactivado en la configuración del proyecto.

Pasos para resolverlo:

1. Vaya a Configuración() > funciones de IA > Eddy AI en el portal de la base de conocimientos.

2. En la sección AI search suite , asegúrese de que la casilla de verificación API pública esté seleccionada.

   

3. Si el problema persiste después de seguir estos pasos, póngase en contacto con el equipo de soporte de Document360 para obtener más ayuda: Póngase en contacto con el equipo de soporte de Document360

Videos relacionados

Experimente nuestra moderna documentación de API en Document360 como nunca antes

Pruebe los puntos de conexión de la API directamente desde la documentación con la función Pruébelo

Información adicional

Presentación de la documentación de la API: Mejore su experiencia con la API - Haga clic para leer