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 especificaciones 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

Comprensión de la eliminación de endpoints durante la resincronización

Cuando actualizas tu archivo de especificación de la API, cualquier endpoint que ya no esté presente en la nueva especificación se elimina permanentemente, junto con cualquier contenido personalizado añadido a esas páginas de endpoint.

Para actualizar tu archivo de especificación de API:

1. Sube el archivo actualizado de especificación de la API a la ventana de referencia Editar API .

2. Si se elimina algún endpoint, se muestra una advertencia. Haz clic en Mostrar endpoints eliminados para revisar la lista de endpoints afectados.

3. Selecciona la casilla Confirmar para continuar para reconocer la eliminación.

4. Haz clic en Actualizar para continuar.

Los endpoints eliminados se trasladan a la papelera de reciclaje, donde pueden previsualizarse hasta 30 días pero no pueden restaurarse.

 NOTA

Si estás usando el endpoint de la API de resync de forma programática, envía ForceImport = false tu solicitud para previsualizar la lista de endpoints que se eliminarán sin proceder con la eliminación. Envía ForceImport = true para confirmar y procede.

Descargar código fuente de la API

NOTA

Para descargar los archivos de la API, asegúrate de que el interruptor Mostrar el código fuente de la API en la configuración del portal de la Base de Conocimiento esté activado .

Enlaces útiles