Administración de la documentación de la API

La función de documentación de la API de Document360 facilita la creación de documentación clara e interactiva mediante la carga de los archivos de especificación de la API. Este proceso crea automáticamente documentación detallada que cubre todo, desde los puntos finales de la API hasta los métodos y las respuestas, lo que ayuda a los desarrolladores a comprender y usar su API de manera más efectiva.  

Generación de documentación de API

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

• Desde una URL

• Desde un  archivo JSON/YAML/YML

• Con un flujo de CI/CD

NOTA

Document360 es compatible con las especificaciones de API 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 de API a partir de un archivo de especificación de API (JSON/YAML/YML),

1. Vaya al proyecto deseado en el portal de la base de conocimientos.

2. Seleccione Documentación de la API ({ }) en la barra de navegación izquierda.

3. Haga clic en el menú desplegable Crear en la barra de navegación superior y seleccione Nueva API. Esto mostrará la ventana Nueva referencia de API .

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

5. Haga clic en Cargar desde mi dispositivo o en Elegir de Drive para seleccionar el archivo de su dispositivo o de Document360 Drive, respectivamente. También puede arrastrar y soltar su archivo directamente en la ventana de referencia de la nueva API.

NOTA

El proceso de importación de documentación de API admite subcategorías de segundo nivel que utilizan el > símbolo en las etiquetas OpenAPI (por ejemplo, Pets > Details). Esto permite una organización más limpia y anidada de los puntos finales, conserva 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 el archivo cargado tiene alertas o advertencias asociadas, puede verlas expandiendo los menús desplegables Alertas y Advertencias , que aparecen en la ventana Nueva referencia de API.

6. Haga clic en Nueva referencia de API para navegar a la ventana de confirmación de publicación . Verá un mensaje de éxito en la ventana, junto con la cantidad de categorías y artículos que se han creado.

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

NOTA

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

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

Para cargar el archivo de especificación de API como una URL en Document360,

1. Vaya al proyecto deseado en el portal de la base de conocimientos.

2. Seleccione Documentación de la API ({ }) en la barra de navegación izquierda.

3. Haga clic en el menú desplegable Crear en la barra de navegación superior y seleccione Nueva API o haga clic en el botón Nueva API en la esquina superior derecha. Esto mostrará el panel de referencia de la nueva API .

4. En la pantalla Elegir origen , seleccione el botón de opción Crear a partir de URL y haga clic en Siguiente.

5. En la pantalla Configuración de origen , introduzca la URL del archivo de especificación de API en el campo URL .

6. Haga clic en Agregar referencia de API para navegar a la pantalla Finalizar .

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

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

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

Antes de cargar un archivo de especificación de API con un flujo de CI/CD, asegúrese de que la versión más reciente de Node.js esté instalada en el sistema. Si no está familiarizado con Node.js, consulte las instrucciones de this guide instalación.

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

1. Vaya al proyecto deseado en el portal de la base de conocimientos.

2. Seleccione Documentación de la API ({ }) en la barra de navegación izquierda.

3. Haga clic en el menú desplegable Crear en la barra de navegación superior y seleccione Nueva API. Esto mostrará la ventana emergente Nueva referencia de API .

4. En la pantalla Elegir origen , seleccione el botón de opción Flujo de CI/CD y haga clic en Siguiente.

5. Copie el comando CLI completo que se muestra en la ventana emergente Nueva referencia de API.

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

   • La ruta de acceso completa al archivo de especificaciones JSON/YAML/YML local. Por ejemplo

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

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

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

7. Pegue el comando actualizado en su terminal y presione Enter.  

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

NOTA

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

• Si vuelve a generar la clave de API haciendo clic en el icono () de la interfaz de usuario, debe actualizar el --apiKey valor del comando de la CLI antes de volver a ejecutarlo. La clave anterior ya no será válida.

Regenerar la documentación de la API

Si realiza algún cambio en la API, como agregar nuevos puntos de conexión, no es necesario actualizar la documentación de la API en Document360 manualmente. Puede volver a generar la documentación de la API y cualquier cambio en la API se reflejará automáticamente en la documentación actualizada.

NOTA

Cualquier contenido personalizado que agregue a la documentación de la API se conservará cuando vuelva a generar la documentación de la API.

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

1. Vaya al proyecto deseado en el portal de la base de conocimientos.

2. Seleccione Documentación de la API ({ }) en la barra de navegación izquierda.

3. Haga clic en Referencia de documentos de API en el panel de la lista de navegación izquierdo.

4. Haga clic en el icono Más () junto a la referencia de API deseada para la que desea volver a generar la documentación de API.

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

      • Haga clic en Resincronizar.

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

   2. Para volver a generar la documentación de la API con una nueva URL:

      • Haga clic en Editar.

      • Introduzca la nueva URL en el campo URL .

      • Haga clic en Actualizar.

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

Regenerar la documentación de la API a partir de un archivo de especificación de la API

1. Vaya al proyecto deseado en el portal de la base de conocimientos.

2. Seleccione Documentación de la API ({ }) en la barra de navegación izquierda.

3. Haga clic en Referencia de documentos de API en el panel de la lista de navegación izquierdo.

4. Haga clic en el Más icono () situado junto a la referencia de API deseada para la que desea volver a generar la documentación de la API.

5. Haga clic en Editar.

6. Cargue el archivo de especificación de API más reciente en formato JSON/YAML/YML.

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

Regenerar la documentación de la API integrada con el flujo de CI/CD

Puede volver a sincronizar la referencia de la API en las canalizaciones de CI/CD con la ayuda de los paquetes npm de d360. D360 es la herramienta de línea de comandos que le ayuda a configurar flujos de trabajo que sincronizan los documentos de la API con Document360.

También puede realizar la resincronización manualmente usando el siguiente comando.

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 API, asegúrese de que la opción Mostrar referencia de API de descarga en la configuración del portal de la base de conocimientos esté activada.

Solución de problemas

Falta o es incorrecta la URL del servidor en OpenAPI

Error: Este error se produce cuando falta la URL del servidor o está configurada incorrectamente en la especificación OpenAPI. Como resultado, los usuarios de la API no saben dónde enviar las solicitudes de la API y es posible que el botón "Pruébalo" no esté disponible en la documentación de la API. La causa principal suele ser una sección faltante o incorrecta servers en la especificación de OpenAPI.

Pasos para resolver

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

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

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

2. Para las API basadas en regiones, defina varias direcciones URL 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úrese de que todos los clientes de API (por ejemplo, Postman, cURL) utilicen la URL del servidor correcta al realizar solicitudes.

NOTA

Las URL anteriores son ejemplos. Consulte la configuración específica de su API para obtener la URL correcta del servidor.

Ejemplo:

Ejemplo de YAML para faltantes 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úrese de que el servers se define correctamente en la especificación OpenAPI para evitar que los consumidores de API tengan que construir URL de solicitud de API manualmente.

Error 401 no autorizado de la URL incorrecta del servidor

Error: Este error se produce cuando las solicitudes de API devuelven una respuesta 401 no autorizada. 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  causa fallas de autenticación.

Pasos para resolver:

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

1. Asegúrese de que las solicitudes de API utilicen el punto de conexión basado en región correcto.

2. Confirme que se están usando el identificador de cliente y el secreto de cliente correctos.

Ejemplo de una solicitud de API correcta:

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

NOTA

La URL anterior es un ejemplo. Consulte la configuración específica de su API para obtener la URL correcta del servidor.

3. Asegúrese de que el token de autenticación se incluya correctamente en los encabezados de solicitud.

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

Error: Este problema se produce cuando los consumidores de 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 esté configurada correctamente en la especificación OpenAPI.

Pasos para resolver:

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

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

Ejemplos:

Tabla comparativa: URL del servidor presente frente a falta

NOTA

Las URL anteriores son ejemplos. Consulte la configuración específica de su API para obtener la URL correcta del servidor.

Para evitar este problema, asegúrese 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ébelo" con un archivo OAS

Error:

Después de cargar con éxito un archivo OAS, al hacer clic en la función Pruébelo , se produce un error 403. Este error se produce cuando al archivo OAS le falta una definición para el mecanismo de seguridad BearerAuth .

Pasos para resolver:

Para resolver el error 403, siga estos pasos:

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

2. Si falta la definición de BearerAuth , incluya la definición de seguridad de BearerAuth en el archivo OAS y vuelva a cargarla.

3. Durante el proceso de importación, verifique si se activa alguna alerta relacionada con la autenticación de portador y abórdela 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 tiene formato JSON, que utiliza el escape (\") para manejar ciertos caracteres de forma segura. Este escape altera caracteres como comillas, barras invertidas y nuevas líneas para evitar errores de transmisión de datos. Sin embargo, si los caracteres de escape no se vuelven a convertir (sin escape), la estructura HTML puede romperse, lo que provoca problemas de estilo cuando se representa.

Por ejemplo, un simple párrafo HTML:

<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 de escape (\") garantizan que el JSON siga siendo válido, pero si no se escapa, es posible que el HTML no se represente correctamente.

Pasos para resolver

1. Recupere el contenido HTML a través de la API e inspeccione la respuesta.

2. Busque caracteres de escape en la respuesta JSON, como:

   • \" (comillas dobles escapadas)

   • \\ (barras invertidas escapadas)

   • \n (nueva línea)

   • \t (pestaña)

3. Anule el escape del contenido JSON antes de renderizarlo. Esto restaurará la estructura HTML original.

4. Verifique el estilo después de quitar el escape para asegurarse de que el contenido aparezca correctamente.

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

   

   Una vez que no se escape correctamente, el HTML se mostrará como se esperaba, evitando discrepancias de estilo.

Las variables y los fragmentos de código no se representan en la respuesta de la API

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

• 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 reemplazan con valores reales, lo que hace que el contenido sea adecuado para mostrarlo a los usuarios finales.

• Si "isForDisplay" = false (o no se establece), la respuesta de la API contendrá variables y fragmentos de código sin procesar, 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 conocimientos:

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

Respuesta de la 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 de la API con "isForDisplay"=true:

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

Pasos para resolver:

1. Recupere el contenido del artículo a través de la API e inspeccione la respuesta.

2. Compruebe si las variables o fragmentos de código aparecen sin procesar en la respuesta.

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

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

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

5. Verifique si la respuesta de la API ahora muestra las variables y fragmentos de código representados correctamente.

6. Si el problema persiste, asegúrese de que el sistema que procesa la respuesta de la API gestiona y muestra el contenido representado correctamente.

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

Cuerpo vacío que se muestra 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 al esquema OpenAPI le falta el “type": "object” atributo en una o varias definiciones de objeto.

Pasos para resolver:

Asegúrese de que todas las definiciones de objeto de la especificación de OpenAPI incluyan “type": "object”archivos . Este atributo especifica claramente que la estructura definida es un objeto, lo que ayuda a mantener la claridad y la coherencia en la documentación de la API. Permite que las herramientas de documentación de API representen con precisión los parámetros del cuerpo de la solicitud, los esquemas de respuesta y otras definiciones de objetos, lo que facilita a los desarrolladores comprender e interactuar con su API.

Problema al agregar una referencia de API

Error: No se puede agregar una referencia de API. Esta operación no se puede completar. Asegúrese de haber proporcionado un archivo de especificaciones válido.

La posible causa puede ser que el archivo de especificación cargado (YAML) tenga un formato incorrecto y no sea un YAML de OpenAPI 3.0 válido. Esto sucede a menudo cuando el archivo se copia o exporta desde un editor de texto enriquecido, lo que presenta problemas de formato.

Pasos para resolver:

1. Valide su archivo de especificaciones: abra su archivo YAML en una herramienta como Swagger Editor o un editor de código para verificar si hay errores o problemas de formato.

2. Buscar caracteres de formato no deseados: Compruebe si hay caracteres como \f0\fs24 barras invertidas o barras diagonales inversas \ finales que puedan haberse introducido durante copiar y pegar desde una fuente de texto enriquecido. Estos pueden romper el formato YAML.

3. Limpiar el archivo: use un editor de código o texto sin formato para eliminar los caracteres de formato especiales. Evite usar procesadores de texto al editar o guardar archivos YAML.

4. Vuelva a cargar el archivo: después de limpiar el archivo y asegurarse de que es un YAML OpenAPI 3.0 válido, intente cargarlo nuevamente.

Enlaces útiles