Administración de la documentación de la API

Planes que respaldan la documentación 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 de conexión 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

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

• Desde una URL

• Desde un  archivo JSON/YAML

• Con un flujo de CI/CD

NOTA

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

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. Navegue hasta el proyecto deseado en el portal de la base de conocimientos.

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

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

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

5. Haga clic en Cargar desde mi dispositivo o en Elegir desde Drive para seleccionar el archivo desde su dispositivo o desde Document360 Drive, respectivamente. También puedes arrastrar y soltar tu archivo directamente en la ventana de referencia de la Nueva 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 de referencia Nueva API.

6. Haga clic en Nueva referencia de API para ir a la ventana de confirmación de publicación . Verá un mensaje de éxito en la ventana, junto con el número 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. Su 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 especificaciones de la API como URL en Document360,

1. Navegue hasta el proyecto deseado en el portal de la base de conocimientos.

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

3. Haga clic en el menú desplegable Crear de 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 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 la 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 su archivo de especificación de API.

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

NOTA

Si desea verificar la documentación de la API antes de publicarla, haga clic en Cerrar en la pantalla Finalizar para volver a la pantalla Documentación. Podrás ver los borradores de la documentación de tu API en el panel Categorías y artículos .

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 this guide para obtener instrucciones de instalación.

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

1. Navegue hasta el proyecto deseado en el portal de la base de conocimientos.

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

3. Haga clic en el menú desplegable Crear de la barra de navegación superior y seleccione Nueva API. Esto mostrará la ventana emergente de referencia Nueva 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 apunte al archivo de especificaciones de la API. Por ejemplo

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

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

8. Se cargará el archivo de especificaciones de la API yse generará la documentación de la 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 valor en el comando de la --apiKey CLI antes de volver a ejecutarlo. La clave antigua ya no será válida.

Volver a generar la documentación de la API

Si realiza algún cambio en la API, como añadir puntos finales, no es necesario que actualice manualmente la documentación de la API en Document360. Simplemente puede volver a generar la documentación de su API, y cualquier cambio en su API se reflejará automáticamente en la documentación de la API.

NOTA

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

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

1. Navegue hasta el proyecto deseado en el portal de la base de conocimientos.

2. Seleccione Documentación de la API ({ }) enla 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 la API.

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

      • Haga clic en Volver a sincronizar.

      • La documentación de la API se volverá a generar según el archivo de especificación de la API más reciente.

   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 volverá a generar según el archivo de especificaciones de la API en la nueva URL.

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

1. Navegue hasta el proyecto deseado en el portal de la base de conocimientos.

2. Seleccione Documentación de 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 la API.

5. Haga clic Editar.

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

7. Haga clic en Actualizar. La documentación de la API se volverá a generar según el archivo de especificación de la API más reciente.

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

Puede volver a sincronizar la referencia de API en las canalizaciones de CI/CD con la ayuda de los paquetes d360 npm. D360 es la herramienta de línea de comandos que le ayuda a configurar flujos de trabajo que sincronizan sus documentos de 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 la referencia de la 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 una URL de servidor incorrecta o falta en OpenAPI

Error: Este error se produce 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 a dónde enviar las solicitudes de API y es posible que el botón "Pruébelo" no esté disponible en la documentación de la API. La causa raíz 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 de OpenAPI incluya la URL de servidor correcta:

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

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

2. En el caso de 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 (Postman, cURL, etc.) utilicen la URL de servidor correcta al realizar solicitudes.

NOTA

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

Ejemplo:

Ejemplo de YAML para faltar 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 de OpenAPI para evitar que los consumidores de API tengan que construir manualmente las URL de solicitud de API.

Error no autorizado 401 de URL de servidor incorrecta

Error: Este error se produce cuando las solicitudes de API devuelven una respuesta 401 no autorizada. Suele ocurrir cuando se utiliza una URL de servidor incorrecta en las solicitudes de API. Por ejemplo, el uso https://apihub.document360.io de instead of provoca errores de https://apihub.us.document360.io autenticación.

Pasos para resolverlo:

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 utilizando el ID 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 conocer la URL del servidor correcta.

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

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

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

Pasos para resolverlo:

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 vs. faltante

NOTA

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

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ébalo , 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 resolverlo:

Para resolver el error 403, siga estos pasos:

1. Compruebe si la definición de seguridad 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 activan alertas relacionadas con la autenticación del portador y resuélvalas 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 el escape (\") para manejar ciertos caracteres de forma segura. Este escape altera caracteres como comillas, barras invertidas y saltos de línea 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>

Puede 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 anular el escape para asegurarse de que el contenido aparezca correctamente.

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

   

   Una vez que se elimine 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 su visualización a los usuarios finales.

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

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

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

Respuesta de la API con "isForDisplay"=true:

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

Pasos para resolverlo:

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

2. Compruebe si las variables o los fragmentos 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 los fragmentos renderizados correctamente.

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

7. Al actualizar artículos a través de la API, no pase el contenido completamente representado para evitar reemplazar los 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 del 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 resolverlo:

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 la 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 la comprensión y la interacción con la API.

Enlaces útiles