Gestión de la documentación de la API

La función de documentación de la API en Document360 facilita la creación de documentación clara e interactiva subiendo tus archivos de especificación de la API. Este proceso crea automáticamente una documentación detallada que abarca desde endpoints de API hasta métodos y respuestas, ayudando a los desarrolladores a entender y utilizar tu API de forma más eficaz.  

Generación de documentación de API

Existen tres métodos para generar documentación de API en Document360:

• De una URL

• Desde un archivo JSON/YAML/YML

• Con un flujo CI/CD

NOTA

Document360 es compatible con las especificaciones OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 y Postman.

Generación de documentación de API a partir de un archivo de especificación de API

Para generar referencias API a partir de un archivo de especificación API (JSON/YAML/YML),

1. Navega hasta el proyecto deseado en el portal de la base de conocimiento.

2. Selecciona documentación de la API ({ }) en la barra de navegación izquierda.

3. Haz clic en el desplegable Crear en la barra de navegación superior y selecciona Nueva API. Esto mostrará la ventana de referencia de la nueva API .

4. Seleccione el botón de opción Cargar definición de API en la ventana de referencia de Nueva API .

5. Haz clic en Subir desde mi dispositivo o Elegir entre Drive para seleccionar el archivo desde tu dispositivo o Document360 Drive, respectivamente. También puedes arrastrar y soltar tu archivo directamente en la ventana de referencia de la nueva API.

NOTA

El proceso de importación de documentación API soporta subcategorías de segundo nivel usando el > símbolo en etiquetas OpenAPI (por ejemplo, Pets > Details). Esto permite una organización más limpia y anidada de los endpoints, preserva la estructura durante la resincronización y garantiza una visualización y navegación adecuadas en el panel izquierdo de la referencia de la API.

Si tu archivo subido tiene alertas o advertencias asociadas, puedes verlas ampliando los menús desplegables de Alertas y Advertencias , que aparecen en la ventana de referencia de la nueva API.

6. Haz clic en Nueva referencia de API para acceder a la ventana de confirmación de publicación . Verás un mensaje de éxito en la ventana, junto con el número de categorías y artículos que se han creado.

7. Haz clic en Publicar para generar la documentación de tu API.

NOTA

Para revisar tu documentación antes de publicarla, haz clic en Cerrar para volver a la pantalla de Documentación. Tu borrador será visible en el panel de Categorías y Artículos .

Generación de documentación de API a partir de una URL

Para subir el archivo de especificación de la API como URL a Document360,

1. Navega hasta el proyecto deseado en el portal de la base de conocimiento.

2. Selecciona documentación de la API ({ }) en la barra de navegación izquierda.

3. Haz clic en el desplegable Crear desde la barra de navegación superior y selecciona Nueva API o haz clic en el botón de Nueva API en la esquina superior derecha. Esto mostrará el panel de referencia de la nueva API .

4. En la pantalla Elegir fuente , selecciona el botón de opción Crear desde URL y haz clic en Siguiente.

5. En la pantalla de configuración de Fuente , introduce la URL de tu archivo de especificación de API en el campo URL .

6. Haz clic en Añadir referencia de API para navegar a la pantalla de Terminar .

7. En la pantalla de Finalizar , podrás ver el número de categorías y artículos que se han creado para tu archivo de especificaciones de la API.

8. Haz clic en Publicar para generar la documentación de tu API.

Generación de documentación API con un flujo CI/CD

Antes de subir un archivo de especificación de API con un flujo CI/CD, asegúrate de que la última versión de Node.js esté instalada en tu sistema. Si no conoces Node.js, consulta esta guía para las instrucciones de instalación.

Para subir el archivo de especificación de la API con un flujo CI/CD,

1. Navega hasta el proyecto deseado en el portal de la base de conocimiento.

2. Selecciona documentación de la API ({ }) en la barra de navegación izquierda.

3. Haz clic en el desplegable Crear en la barra de navegación superior y selecciona Nueva API. Esto mostrará la ventana de referencia de la nueva API .

4. En la pantalla Elegir fuente , selecciona el botón de radio CI/CD Flow .

5. Copia el comando CLI completo mostrado desde la ventana de referencia de la nueva API .

6. En el comando copiado, actualiza el --path valor con:

   • El camino completo a tu archivo local de especificaciones JSON/YAML/YML. Por ejemplo,

     --path=/Users/yourname/projects/api/openapi.yaml

   • Una URL válida que apunta a tu archivo de especificaciones de la API. Por ejemplo,

     --path=https://example.com/api/openapi.yaml

7. Pega el comando actualizado en tu terminal y pulsa Enter.  

8. Se cargará tu archivo de especificación de la API y se generará la documentación de la API.

NOTA

• La primera línea (npm install d360 -g) instala la herramienta CLI de Document360. Solo tienes que ejecutarlo la primera vez. Si ya está instalado, puedes saltarte esa línea.

• Si regeneras la clave API haciendo clic en el icono () en la interfaz, debes actualizar el --apiKey valor en tu comando CLI antes de ejecutarlo de nuevo. La clave antigua dejará de ser válida.

Gestión de webhooks (eventos)

Cuando tu especificación OpenAPI 3.1 incluye webhooks, Document360 los importa y muestra un icono de evento junto a cada webhook. La página muestra el esquema de la carga útil y el ejemplo. Si la especificación no incluye un ejemplo, se muestra un ejemplo por defecto y una carga útil de muestra. Prueba que no está disponible para webhooks. Los Webhooks se incluyen en las operaciones de resincronización, y tu contenido personalizado se mantiene tras la regeneración.

Documentación de regeneración de API

Si realizas algún cambio en tu API, como añadir nuevos endpoints, no necesitas actualizar manualmente la documentación de la API en Document360. Puedes regenerar la documentación de tu API, y cualquier cambio en tu API se reflejará automáticamente en la documentación actualizada.

NOTA

Cualquier contenido personalizado que añadas a la documentación de tu API se conservará cuando regeneres la documentación de la API.

Regenera la documentación de la API a partir de la URL

1. Navega hasta el proyecto deseado en el portal de la base de conocimiento.

2. Selecciona documentación de la API ({ }) en la barra de navegación izquierda.

3. Haz clic en referencias API desde el panel de navegación izquierdo de la lista.

4. Haz clic en el icono de Más () junto a la referencia de API deseada para la que quieres regenerar la documentación de la API.

   1. Para regenerar la documentación de la API a partir de la URL existente:

      • Haz clic en Resincronizar.

      • La documentación de la API se regenerará según el último archivo de especificaciones de la API.

   

   1. Para regenerar la documentación de la API con una nueva URL:

      • Haz clic en Editar.

      • Introduce la nueva URL en el campo URL .

      • Haz clic en Actualizar.

      • La documentación de la API se regenerará según el archivo de especificación de la API en la nueva URL.

Regenera documentación de API a partir de un archivo de especificación de API

1. Navega hasta el proyecto deseado en el portal de la base de conocimiento.

2. Selecciona documentación de la API ({ }) en la barra de navegación izquierda.

3. Haz clic en referencias API desde el panel de navegación izquierdo de la lista.

4. Haz clic en el icono Más () junto a la referencia de API deseada para la que quieres regenerar la documentación de la API.

5. Haz clic Editar.

6. Sube el último archivo de especificación de la API en formato JSON/YAML/YML.

7. Haz clic en Actualizar. La documentación de la API se regenerará según el último archivo de especificaciones de la API.

Documentación de regeneración de API integrada con flujo CI/CD

Puedes resincronizar la referencia de API en tus pipelines CI/CD con la ayuda de tus paquetes d360 npm. D360 es la herramienta de línea de comandos que te ayuda a configurar flujos de trabajo que sincronizan tu documentación API con Document360.

También puedes realizar la resincronización manualmente usando el comando que aparece a continuación.

d360 apidocs:resync 
                    --apiKey=API_key_value
                    --userId=user_id_value
                    --apiReferenceId=API_reference_value
                    --path=Spec_file_path

Descargar referencia de API

NOTA

Para descargar los archivos de la API, asegúrate de que el interruptor de referencia de la API Show Download en la configuración del portal de la Knowledge Base esté activado.

Resolución de problemas

URL de servidor faltante o incorrecta en OpenAPI

 Error: Este error ocurre cuando falta la URL del servidor o está configurada incorrectamente en la especificación de OpenAPI. Como resultado, los usuarios de la API no saben dónde enviar las solicitudes de la API, y el botón "Pruébalo" puede no estar disponible en la documentación de la API. La causa raíz suele ser una sección ausente o incorrecta servers en la especificación de OpenAPI.

Pasos para resolver

Para resolver este problema, asegúrese de que la especificación de OpenAPI incluya la URL correcta del servidor:

1. Define la URL del servidor en la especificación de OpenAPI:

   servers:
     - url: https://apihub.document360.io
       description: Main API hub

2. Para APIs basadas en regiones, define múltiples URLs de servidor:

   servers:
     - url: https://apihub.document360.io
       description: Global API hub
     - url: https://apihub.us.document360.io
       description: US region API hub

3. Asegúrate de que todos los clientes de API (por ejemplo, Postman, cURL) usen la URL correcta del servidor al realizar solicitudes.

NOTA

Las URLs anteriores son ejemplos. Por favor, consulta la configuración específica de tu API para encontrar la URL correcta del servidor.

Ejemplo:

Ejemplo YAML de ausencia servers   Sección:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    userName:
                      type: string

Para evitar este problema, asegúrate de que servers la sección está correctamente definida en la especificación de OpenAPI para evitar que los consumidores de API tengan que construir manualmente las URLs de solicitud de la API.

Error no autorizado 401 por URL incorrecta del servidor

Error: Este error ocurre cuando las solicitudes de API devuelven una respuesta no autorizada 401 . Normalmente ocurre cuando se utiliza la URL incorrecta del servidor en las solicitudes de API. Por ejemplo, usar https://apihub.document360.io en lugar de https://apihub.us.document360.io provoca fallos de autenticación.

Pasos para resolver:

Para resolver este problema, sigue estos pasos para asegurar el uso correcto de la URL del servidor y la autenticación adecuada:

1. Asegúrate de que las solicitudes API usen el punto final regional correcto.

2. Confirma que se están usando el ID de cliente correcto y el secreto del cliente.

Ejemplo de una solicitud API correcta:

GET https://apihub.us.document360.io/v2/Articles/{article_id}/en?appendSASToken=true

NOTA

La URL anterior es un ejemplo. Por favor, consulta la configuración específica de tu API para encontrar la URL correcta del servidor.

3. Asegúrate de que el token de autenticación esté correctamente incluido en las cabeceras de la solicitud.

URL del servidor ausente en la documentación de la API

Error: Este problema ocurre cuando los consumidores de la API no están seguros de qué URL base usar para sus solicitudes. Esto suele ocurrir cuando la documentación no indica claramente la URL del servidor, aunque pueda estar correctamente configurada en la especificación de OpenAPI.

Pasos para resolver:

Para evitar confusiones y asegurar que los consumidores de API conozcan la URL base correcta:

1. Especifica la URL base explícitamente en la documentación de la API.

Ejemplos:

Tabla comparativa: URL del servidor presente vs. ausente

NOTA

Las URLs anteriores son ejemplos. Por favor, consulta la configuración específica de tu API para encontrar la URL correcta del servidor.

Para evitar este problema, asegúrate de que la documentación de la API especifique claramente la URL del servidor para evitar confusiones.

Error 403 al usar la función "Pruébalo" con un archivo OAS

Error:

Tras subir con éxito un archivo OAS, hacer clic en la función Pruébalo da un error 403. Este error ocurre cuando el archivo OAS carece de una definición para el mecanismo de seguridad BearerAuth .

Pasos para resolver:

Para resolver el error 403, sigue estos pasos:

1. Comprueba si la definición de seguridad de BearerAuth está presente en tu archivo OAS.

2. Si falta la definición de BearerAuth , incluye la definición de seguridad de BearerAuth en el archivo OAS y vuelve a subirla.

3. Durante el proceso de importación, verifica si se activan alertas relacionadas con la Autenticación por Portador y diríjalas en consecuencia.

Estilo HTML incorrecto en la respuesta de la API

Al recuperar el contenido HTML de un artículo a través de una API, la respuesta se formatea en JSON, que utiliza escaping (\") para manejar ciertos caracteres de forma segura. Este escape altera caracteres como comillas, barras y nuevas líneas para evitar errores en la transmisión de datos. Sin embargo, si los caracteres escapados no se revierten (no escapados), la estructura HTML puede fallar, lo que puede causar problemas de estilo al renderizarse.

Por ejemplo, un párrafo HTML sencillo:

<p>This is a "sample" paragraph.</p>

Podría aparecer en la respuesta JSON como:

"<p>This is a \"sample\" paragraph.</p>"

Las comillas dobles escapadas (\") aseguran que el JSON siga siendo válido, pero si no se desbloquea, el HTML podría no renderizarse correctamente.

Pasos para resolver

1. Recupera el contenido HTML a través de la API e inspecciona la respuesta.

2. Busca personajes fugados en la respuesta JSON, como:

   • \" (comillas dobles escapadas)

   • \\ (cortes escapados)

   • \n (línea de nuevo)

   • \t (tab)

3. Deshazla del contenido JSON antes de renderizarlo. Esto restaurará la estructura HTML original.

4. Verifica el estilo después de la desfuga para asegurarte de que el contenido se ve correctamente.

5. Si el problema persiste, comprueba si modificaciones adicionales en tu código están alterando la respuesta de la API.

   

   Una vez que se desbloquea correctamente, el HTML se mostrará como se espera, evitando discrepancias de estilo.

Variables y fragmentos que no se renderizan en la respuesta API

Al recuperar contenido de un artículo a través de la API, variables y fragmentos pueden aparecer sin procesar (por ejemplo, {{variable.UserName}} en lugar de valores reales). Esto suele ocurrir cuando el "isForDisplay" parámetro no está correctamente configurado.

• Si "isForDisplay" = true, la API devolverá el contenido del artículo con todas las variables y fragmentos completamente renderizados. Esto significa que los marcadores de posición se sustituyen por valores reales, haciendo que el contenido sea adecuado para mostrar a los usuarios finales.

• Si "isForDisplay" = false (o no está activado), la respuesta de la API contendrá variables y fragmentos no procesados, que pueden no ser útiles para la visualización directa.

  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

Contenido del artículo en la base de conocimiento:

Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}.

Respuesta API sin "isForDisplay":

"Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}."

Las variables permanecen sin procesar, lo que hace que no sea adecuado para la visualización directa.

Respuesta API con "isForDisplay"=true:

"Welcome, John! Here’s how to use Document360."

Pasos para resolver:

1. Recupera el contenido del artículo mediante API e inspecciona la respuesta.

2. Comprueba si las variables o fragmentos aparecen sin procesar en la respuesta.

3. Asegúrate de que la solicitud API incluya el "isForDisplay" parámetro. Si falta, modifica la solicitud para incluir "isForDisplay": true.

4. Envía la solicitud de API modificada. Ejemplo de solicitud:

   {
     "articleId": "12345",
     "isForDisplay": true
   }

5. Verifica si la respuesta de la API ahora muestra las variables y fragmentos correctamente renderizados.

6. Si el problema persiste, asegúrese de que el sistema que procesa la respuesta API gestione y muestre correctamente el contenido renderizado.

7. Al actualizar artículos a través de la API, no pases contenido completamente renderizado para evitar reemplazar los marcadores de posición dinámicos por valores estáticos.

Cuerpo vacío mostrado en la documentación de la API debido a la falta de tipo de esquema

La documentación de la API muestra un cuerpo vacío. La posible causa de este error podría ser que el esquema OpenAPI carece del “type": "object” atributo en una o más definiciones de objetos.

Pasos para resolver:

Asegúrate de que cada definición de objeto en tu especificación OpenAPI incluya “type": "object”. Este atributo especifica claramente que la estructura definida es un objeto, ayudando a mantener claridad y coherencia en la documentación de tu API. Permite a las herramientas de documentación de la API renderizar con precisión los parámetros del cuerpo de las solicitudes, los esquemas de respuesta y otras definiciones de objetos, facilitando la comprensión e interacción de los desarrolladores con tu API.

Problema al añadir una referencia de API

Error: No se puede añadir referencia de API. Esta operación no puede completarse. Por favor, asegúrate de haber proporcionado un archivo de especificaciones válido.

La posible causa podría ser que el archivo de especificación subido (YAML) esté malformado y no sea un YAML válido de OpenAPI 3.0. Esto suele ocurrir cuando el archivo se copia o exporta desde un editor de texto enriquecido, lo que introduce problemas de formato.

Pasos para resolver:

1. Valida tu archivo de especificaciones: Abre tu archivo YAML en una herramienta como Swagger Editor o un editor de código para comprobar errores o problemas de formato.

2. Busca caracteres de formato no deseados: Revisa si hay caracteres como \f0\fs24 barras inversas \ o que puedan haberse introducido durante copiar-pegar desde una fuente de texto enriquecido. Estos pueden romper el formato YAML.

3. Limpiar el archivo: Utiliza un editor de texto plano o código para eliminar cualquier carácter de formato especial. Evita usar procesadores de texto al editar o guardar archivos YAML.

4. Vuelve a subir el archivo: Después de limpiar el archivo y asegurarte de que es un YAML válido de OpenAPI 3.0, intenta subirlo de nuevo.

Enlaces útiles