Planes que respaldan la documentación {{glossary.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.

Image showing option to create new API

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),

Navegue hasta el proyecto deseado en el portal de la base de conocimientos.
Seleccione Documentación de API ({ }) en la barra de navegación izquierda.
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 .

Document360 interface showing options to upload API definitions and supported formats.

Seleccione la opción Cargar definición de API en la ventana de referencia Nueva API .
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.

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.
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,

Navegue hasta el proyecto deseado en el portal de la base de conocimientos.
Seleccione Documentación de API ({ }) en la barra de navegación izquierda.
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 .
En la pantalla Elegir origen , seleccione el botón de opción Crear a partir de URL y haga clic en Siguiente.
En la pantalla Configuración de origen , introduzca la URL del archivo de especificación de la API en el campo URL .

Creating a new API reference by entering a URL in the designated field.

Haga clic en Agregar referencia de API para navegar a la pantalla Finalizar .
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.
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,

Navegue hasta el proyecto deseado en el portal de la base de conocimientos.
Seleccione API documentation ({ }) en la barra de navegación izquierda.
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 .
En la pantalla Elegir origen , seleccione el botón de opción Flujo de CI/CD y haga clic en Siguiente.
Copie el comando CLI completo que se muestra en la ventana emergente Nueva referencia de API.

Instructions for installing Document360 API using command line interface and npm package.

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
```
Pegue el comando actualizado en su terminal y presione Enter.
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

Navegue hasta el proyecto deseado en el portal de la base de conocimientos.
Seleccione Documentación de la API ({ }) enla barra de navegación izquierda.
Haga clic en Referencia de documentos de API en el panel de la lista de navegación izquierdo.
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.

Image showing edit and resync options

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

Navegue hasta el proyecto deseado en el portal de la base de conocimientos.
Seleccione Documentación de API ({}) en la barra de navegación izquierda.
Haga clic en Referencia de documentos de API en el panel de la lista de navegación izquierdo.
Haga clic en el icono {{variable.More}} () junto a la referencia de API deseada para la que desea volver a generar la documentación de la API.
Haga clic {{variable.Edit}}.
Cargue el archivo de especificación de API más reciente en formato JSON/YAML.
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.

Image showing edit option

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

Portal de la base de conocimientos

Sitio de la base de conocimientos

Para descargar el archivo de referencia de la API desde el sitio de la base de conocimientos, siga los pasos que se indican a continuación:

En el sitio de la base de conocimientos de documentación de API, en el panel de navegación izquierdo, haga clic en el icono {{variable.More}} () situado junto a la referencia de API deseada para la que desea volver a generar la documentación de API.
Haga clic en Descargar referencia de API.
Se descargará en un formato estándar como .json o .yaml.
Se puede acceder a la opción Descargar referencia de API para todos los tipos de carga, incluidos:
- Carga de archivos
- Flujo de CI/CD
- Carga de URL

Para descargar el archivo de referencia de la API desde el portal de la base de conocimientos, siga los pasos que se indican a continuación:

Navegue hasta el proyecto deseado en el portal de la base de conocimientos.
Haga clic en el icono {{variable.More}} () situado junto a la referencia de API deseada en el panel de navegación izquierdo para el que desea descargar la referencia de API.
Haga clic en Descargar referencia de API.
La última versión del archivo de referencia de la API se descargará en su almacenamiento local.
Alternativamente
Haga clic en Referencia de documentos de API en el panel de navegación izquierdo.
En las referencias de API configuradas que se enumeran, haga clic en el icono más () junto a la referencia de API deseada para la que desea descargar la referencia de API.
Haga clic en Descargar referencia de API.
La última versión del archivo de referencia de la API se descargará en su almacenamiento local.

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.

Image showing the toggle to Show download API reference

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:

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

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

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

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:

Asegúrese de que las solicitudes de API utilicen el punto de conexión basado en región correcto.
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.

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:

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

Ejemplos:

Tabla comparativa: URL del servidor presente vs. faltante

Escenario	Comportamiento	Ejemplo
La URL del servidor está presente	Las solicitudes de API funcionan con normalidad	`https://apihub.document360.io/users`
Falta la URL del servidor	Los clientes deben configurar manualmente	`https://your-api-host.com/users`

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 .

API request interface showing authentication, request, and response sections with status codes.

Pasos para resolverlo:

Para resolver el error 403, siga estos pasos:

Compruebe si la definición de seguridad BearerAuth está presente en el archivo OAS.
Si falta la definición de BearerAuth , incluya la definición de seguridad de BearerAuth en el archivo OAS y vuelva a cargarla.
Durante el proceso de importación, verifique si se activan alertas relacionadas con la autenticación del portador y resuélvalas en consecuencia.

Error messages displayed during API reference import, highlighting invalid identifiers.

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

Recupere el contenido HTML a través de la API e inspeccione la respuesta.
Busque caracteres de escape en la respuesta JSON, como:
- \" (comillas dobles escapadas)
- \\ (barras invertidas escapadas)
- \n (nueva línea)
- \t (pestaña)
Anule el escape del contenido JSON antes de renderizarlo. Esto restaurará la estructura HTML original.
Verifique el estilo después de anular el escape para asegurarse de que el contenido aparezca correctamente.
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.
{{snippet.Contact Document360 support}}

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:

Recupere el contenido del artículo a través de la API e inspeccione la respuesta.
Compruebe si las variables o los fragmentos aparecen sin procesar en la respuesta.
Asegúrese de que la solicitud de API incluya el "isForDisplay" parámetro. Si falta, modifique la solicitud para incluir "isForDisplay": true.
Envíe la solicitud de API modificada. Ejemplo de solicitud:
```
{
  "articleId": "12345",
  "isForDisplay": true
}
```
Verifique si la respuesta de la API ahora muestra las variables y los fragmentos renderizados correctamente.
Si el problema persiste, asegúrese de que el sistema que procesa la respuesta de la API controle y muestre correctamente el contenido renderizado.
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.

Preguntas frecuentes

¿Puedo mantener la documentación de la API generada en estado de borrador?

Después de cargar el archivo de referencia de API, si hace clic en Cerrar en lugar de Publicar, todos los artículos de documentación de API generados se mantienen en estado de borrador.

¿Puedo mover un artículo específico de un punto final de API de una carpeta de referencia de API a otra en Document360?

No, no es posible mover un artículo de punto de conexión de API específico de una carpeta de referencia de API a otra. Sin embargo, puede mover artículos de punto de conexión de API entre subcarpetas dentro de la misma carpeta de referencia de API.

¿Puede un artículo de la documentación de la API tener la misma URL que los artículos de la base de conocimientos?

No, un artículo de la base de conocimientos y un artículo de documentación de la API no pueden tener la misma URL. Sin embargo, puede mantenerlos bajo el mismo subdominio.

¿Con qué frecuencia se vuelve a sincronizar un archivo de referencia de API?

Si generó la documentación de la API a partir de una URL o un archivo JSON/YAML, el archivo de referencia de la API no se vuelve a sincronizar automáticamente y tendrá que actualizarse manualmente. Si desea que el archivo de referencia de la API se vuelva a sincronizar automáticamente, se recomienda integrar el archivo de referencia de la API con el flujo de CI/CD.

¿Por qué recibo un error 403 al publicar detalles a través del punto de conexión de la API?

Se produce un error 403 cuando se intenta publicar detalles a través del punto de conexión de la API. Esto sucede cuando el token de API utilizado no tiene el permiso necesario para realizar una solicitud POST. Asegúrese de que el token de API tenga los permisos necesarios para las solicitudes POST. Actualice la configuración del token y vuelva a intentarlo.

Generación de documentación de API

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

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

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

Volver a generar la documentación de la API

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

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

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

Descargar la referencia de la API

Solución de problemas

Falta una URL de servidor incorrecta o falta en OpenAPI

Error no autorizado 401 de URL de servidor incorrecta

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

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

Estilo HTML incorrecto en la respuesta de la API

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

Cuerpo vacío que se muestra en la documentación de la API debido a la falta del tipo de esquema

Preguntas frecuentes

¿Puedo mantener la documentación de la API generada en estado de borrador?

¿Puedo mover un artículo específico de un punto final de API de una carpeta de referencia de API a otra en Document360?

¿Puede un artículo de la documentación de la API tener la misma URL que los artículos de la base de conocimientos?

¿Con qué frecuencia se vuelve a sincronizar un archivo de referencia de API?

¿Por qué recibo un error 403 al publicar detalles a través del punto de conexión de la API?

Enlaces útiles