Empezando con la documentación de la API

Resumen

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. Tanto si eres una startup que lanza su primera API pública como si eres 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.

Este artículo cubre todo lo que necesitas saber: configurar tu primera referencia de API, elegir el método de importación adecuado, asegurar endpoints con autenticación, probar en tiempo real con Try It!, gestionar webhooks, ejecutar pipelines integrados CI/CD y seguir las mejores prácticas que separan la buena documentación de la API de la realmente buena.

¿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 de API sigue un formato estricto y estructurado derivado de un archivo de especificación legible por máquina (como OpenAPI).

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 la API vs. documentación regular

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 especificación compatibles

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.

Elegir un formato: 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.

Además, la función Pruébalo! en Document360 te permite probar endpoints de API directamente en la base de Knowledge base site. La consola interactiva en el sitio de la base de conocimiento permitirá a los desarrolladores introducir los parámetros necesarios y ejecutar llamadas a la API, obteniendo respuestas en tiempo real. Esta función es útil para resolver problemas y entender cómo se comporta una API sin salir de la documentación ni escribir código.

NOTA

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 (eventos) 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. Prueba que no está disponible para webhooks. Los Webhooks son compatibles para subidas de archivos, importaciones de URL y flujos CI/CD.

Incorporación de documentación de 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 ofrece una experiencia de incorporación más fluida. Si seleccionas la documentación de la API como caso de uso, serás redirigido al flujo de configuración de la API, donde puedes crear referencias de API usando las opciones disponibles.

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

• Archivo API de subida: Soporta archivos JSON/YAML/YML (colecciones OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 y Postman).

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

• Prueba un ejemplo de archivo API de tienda de mascotas: Si no tienes un archivo API listo, puedes usar el archivo de ejemplo (API de tienda de mascotas) que ofrece Document360 para llenar tu espacio de trabajo.

Subida 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 Subido archivo de API. A continuación, haz clic en Subir desde mi dispositivo o arrastra y suelta tu archivo de especificación de API desde tu dispositivo.

NOTA

Los formatos de archivo soportados 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.

• Si se detectan alertas o advertencias en el archivo subido, se mostrará una visión general de alto nivel durante la incorporación. Puedes ver detalles en profundidad en el portal de la base de conocimiento, en la sección de registros, en Más opciones dentro de referencias API.

• Si se detecta algún error en el archivo subido (por ejemplo, formato de archivo no soportado), sustituye el archivo subido por otro alternativo.

Introduciendo una URL de documentación de la API

Para crear una referencia de API a partir de una URL de documentación de la API, seleccione el botón de opción Crear desde URL . A continuación, introduce la URL de tu archivo OpenAPI en la URL del campo de definición de la API . Document360 recuperará y procesará la estructura de la API. Similar a las subidas de archivos,

• Si detectas alguna alerta o advertencia, puedes verla en el portal de la base de conocimiento, en la sección de registros, en Más opciones dentro de referencias de API. Puedes ver detalles en profundidad en el portal de la base de conocimiento, en la sección de registros, en Más opciones dentro de referencias API.

• Si se detecta algún error (por ejemplo, URL inválida), introduce la URL válida para tu archivo OpenAPI.

Saltarse la configuración de la API

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

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

• Estará disponible en modo draft. Puedes revisar los endpoints antes de publicarlos o subir tu 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 quieres saltarte este paso, el dominio será el que está vinculado a tu correo de registro.

Directrices de marca

En el Paso 4, el nombre de tu proyecto, el idioma por defecto, el logotipo de la marca y los colores de la marca se establecen automáticamente en función de la URL que proporciones. Sin embargo, puedes editar estos campos si es necesario. La configuración de idioma de tu navegador determina el idioma por defecto. El inglés se seleccionará por defecto si otros idiomas no soportan el idioma de tu navegador.

NOTA

• Si eliges español o portugués brasileño como idioma predeterminado, el idioma del portal se configurará como español o portugués brasileño. De lo contrario, el inglés será el idioma por defecto.

• El logotipo de la marca y los colores primarios/secundarios se extraen de tu página web. Si decides saltarte este paso, el nombre del proyecto se derivará de tu correo de registro y se aplicará el logo y los colores predeterminados de Document360.

Establecer privacidad documental

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

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

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

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

Por último, haz clic en Siguiente para completar tu flujo de incorporación de la API.

Serás redirigido al espacio de trabajo de documentación de la API, donde:

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

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

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 realiza mediante técnicas de autorización, que controlan el acceso y los permisos. Document360 soporta varios métodos de autorización para proteger tu API, incluyendo:

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

• Token portador: Se autentica con un token generado tras iniciar sesión.

• Clave API: Utiliza una clave única, que se pasa en los encabezados de las solicitudes, para autenticación.

• OAuth2: Protege las APIs mediante diversos flujos, como código de autorización, PKCE, credenciales de cliente y flujos implícitos.

• OpenID Connect: Extiende OAuth2 añadiendo verificación de identidad de usuario.

Consideraciones de autorización (OAuth2 y OpenID)

Al trabajar con APIs que usan OAuth2 u OpenID para autorización, ciertos ajustes son esenciales para un funcionamiento adecuado.

• URI de redirección: Esta es la URL a la que el usuario será redirigido tras completar un flujo de autorización. Asegúrate de configurar 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, por lo que los usuarios no tienen que volver a autenticarse durante su sesión. Esto mantiene su sesión activa sin interrupciones. Para evitar que la autorización caduque durante las sesiones en las que los usuarios interactúan con la función Pruébalo! , Document360 renueva automáticamente el token de actualización en segundo plano. Esto garantiza que los usuarios no tengan que volver a autenticarse manualmente.

Compras

Tendrás acceso a 1 espacio de trabajo API como parte de todos los planes de pago de Document360 (Profesional, Empresarial y Empresarial). Si deseas comprar espacios de trabajo adicionales para API,

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

2. Haz clic en el complemento de compra.

3. Añade el número deseado de espacios de trabajo de documentación de la API. Revisa el coste del complemento y la cantidad pendiente.

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

Resolución de problemas

Problemas de acceso a la API

Error: error 400 – El acceso a la API está deshabilitado. Por favor, contacta con el administrador de tu proyecto.

Este error ocurre cuando el acceso público a la API se desactiva en la configuración del proyecto.

Pasos para resolver:

1. Navega a Configuración() > ajustes de IA > ajustes de IA de Eddy en el portal de la base de conocimiento.

2. En la sección de la suite de búsqueda de IA , asegúrate de que la casilla de verificación de la 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

Problemas con la importación de API

Error: Formato inválido – Fallido la subida del archivo API.

Este error ocurre cuando una o más respuestas en el archivo de especificación de OpenAPI carecen de la sección requerida content .

Aunque el archivo puede pasar la validación en Swagger Editor, Document360 aplica estrictas reglas de validación OpenAPI y requiere que todas las respuestas definan explícitamente el tipo de medio (por ejemplo, application/json) y la referencia del esquema.

Pasos para resolver:

1. Abre tu archivo de especificación OpenAPI (Swagger) en un editor de texto o IDE.

2. Localiza cualquier definición de respuesta que esté vacía o que haga referencia directa a un esquema sin bloque content .

   Ejemplo de respuesta incorrecta:

   responses:
     "200": {}

3. Actualiza la definición de respuesta para incluir una sección de contenido con el tipo de medio y la referencia de esquema correspondientes.

   Ejemplo de respuesta correcta:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/UserGroupFetchResponse"

4. Guarda el archivo y prueba a subirlo de nuevo a Document360.

Resumen y etiquetas no reflejados tras importar una especificación de API

Error: Los endpoints importados no muestran los títulos correctos ni aparecen en las carpetas de etiquetas esperadas.

Este problema ocurre cuando los summary campos y tags en la especificación OpenAPI se definen a nivel de camino en lugar de bajo el objeto de operación (get, post, put, o delete).

Además, el tags campo debe escribirse siempre como un array, incluso cuando solo se usa una etiqueta.

Pasos para resolver:

1. Abre tu archivo de especificación de OpenAPI en un editor de texto.

2. Mueve los campos de resumen y etiquetas dentro de cada objeto de operación.

3. Asegúrate de que el valor de la etiqueta se escriba como un array.

   Ejemplo incorrecto:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     summary: Type & Logical type
     tags: Logical Types
     get:
       ...
   

   Ejemplo correcto:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     get:
       summary: Type & Logical type
       tags: ["Logical Types"]
       ...
   

4. Después de hacer estas actualizaciones, guarda el archivo y reimportalo en Document360.

   Los artículos importados ahora usarán el summary valor como título del artículo, y las carpetas basadas en etiquetas se crearán correctamente.

La página principal de la base de conocimiento redirige a  /apidocs después de la actualización de cuenta

Error: La página principal de la base de conocimiento redirige a  /apidocs y la página no existe

Este problema ocurre cuando un espacio de trabajo de documentación de la API está configurado como acceso público al lector.

Cuando se actualiza la base de conocimiento, el espacio de trabajo de documentación de la API puede configurarse en acceso público por lectores. Como resultado, los visitantes de la página principal de la base de conocimiento son redirigidos automáticamente a la /apidocs página, que no se crea por defecto.

Pasos para resolver:

1. Navega a Configuración () > Usuarios y Permisos en la barra de navegación izquierda del portal de la Base de conocimientos.

2. En el panel de navegación izquierdo, navega hasta Acceso al lector.

3. Localiza el espacio de trabajo de documentación de la API.

4. Pon el acceso del lector en Privado.

Esto detendrá la redirección no intencionada y restaurará el acceso normal a la página principal de tu base de conocimiento.

Vídeos relacionados

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

Endpoints de API de prueba directamente desde Documentación con la función Pruébalo

Información adicional

Presentando la documentación de la API: Mejora tu experiencia API - Haz clic para leer