Este artículo cubre todo lo que necesitas para gestionar tus referencias API en Document360. Crear nuevas referencias, mantenerlas sincronizadas con tu especificación y usar las acciones disponibles para ver, editar, publicar y organizar la documentación de tu API.
Lista de referencias de API
La lista de referencias de API te ofrece una vista central de todas las referencias configuradas de API en tu espacio de trabajo. Para acceder a ella, navega a la documentación de la API ({ }) en la barra de navegación izquierda y haz clic en referencias API en el panel de navegación izquierdo.
Desde aquí puedes ver el nombre, el tipo y la fecha de última actualización de cada referencia. También puedes crear una nueva referencia de API haciendo clic en Nueva API en la esquina superior derecha.
Crear una nueva referencia de API
Para crear una nueva referencia de API, haz clic en el desplegable Crear en la barra de navegación superior y selecciona Nueva API. Esto abre la ventana de referencia de la nueva API, donde tienes cuatro opciones:
- Definición de API de subir - Sube un archivo de especificaciones JSON, YAML o YML directamente desde tu dispositivo o desde Document360 Drive.
- Crear desde URL - Recupera automáticamente tu especificación desde una URL alojada.
- Flujo CI/CD - Integra con tu pipeline para actualizar la documentación automáticamente en cada cambio de especificación. Requiere Node.js.
- Prueba con un archivo API de Pet Store de ejemplo: usa el archivo de especificaciones de muestra de Document360 para explorar el espacio de trabajo antes de subir el tuyo.
Document360 es compatible con las especificaciones OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 y Postman. Dentro de cada espacio de trabajo de API, puedes crear un máximo de 3 referencias API.
Definición de API de subida
- Seleccione el botón de opción Definir la API de Subir .
- Haz clic en Subir desde mi dispositivo para subir desde tu almacenamiento local, o Elige entre Drive para seleccionar un archivo desde Document360 Drive. También puedes arrastrar y soltar tu archivo directamente en la ventana.
- Document360 analiza el archivo y genera la referencia de la API. Si se detectan advertencias, amplía la sección de Alertas y Advertencias para revisarlas.
- Haz clic en Nueva referencia de API para avanzar a la ventana de confirmación de publicación.
Crear desde URL
- Selecciona el botón de opción Crear desde la URL y haz clic en Siguiente.
- Introduce la URL que apunta a tu archivo de especificación de OpenAPI.
- Haz clic en Nueva referencia de API. Document360 recoge y procesa la especificación.
Flujo CI/CD
El flujo CI/CD te permite mantener la documentación de la API sincronizada automáticamente con tu especificación. En lugar de subir manualmente una nueva especificación cada vez que cambia tu API, integras la CLI de Document360 en tu pipeline para que la documentación se actualice automáticamente en cada cambio de especificación.
Para las instrucciones completas de configuración, véase el artículo sobre integración CI/CD .
Acciones de referencia de API
Una vez creada una referencia de API, haz clic en el icono de Más (⋯) junto a ella en la lista de referencias de la API para acceder a las siguientes acciones:
| Acción | Qué hace |
|---|---|
| Edición | Actualiza el archivo de especificación o la URL desde la que se creó la referencia. |
| Resincronización | Regenera la documentación desde la última versión de la especificación en la URL existente. |
| Ver definición de API | Previsualiza el archivo de especificación de la API en bruto. |
| Descargar la fuente original de la API | Descarga la versión actual del archivo de especificaciones en tu almacenamiento local. |
| Publicar | Publica todos los borradores de artículos en la referencia de la API al sitio de la Base de Conocimiento. |
| Borrar | Elimina permanentemente la referencia de la API y todo su contenido generado. |
| Ver registros | Revisa alertas, advertencias y errores de la importación o resincronización más reciente. |
Para permitir que los lectores descarguen el archivo fuente de la API desde el sitio de la Base de Conocimiento, asegúrese de que el interruptor Mostrar el código fuente de la API esté activado en la configuración del portal de la Base de Conocimientos.
Mantener tu documentación sincronizada
Cuando tu API cambia: se añaden nuevos endpoints, se actualizan los parámetros, se modifican las respuestas, pero no necesitas actualizar manualmente tu documentación. Al regenerar la referencia de la API, todos los cambios de tu especificación se extraen automáticamente.
Cualquier contenido personalizado que hayas añadido a artículos de endpoint individuales se conserva cuando regeneras tu documentación. Solo se actualiza el contenido generado por especificaciones.
Resincronización desde una URL existente
- En la lista de referencias de la API, haz clic en el icono de Más (⋯) junto a la referencia que quieres actualizar.
- Haz clic en Resincronizar. La documentación se regenera a partir de la última versión de la especificación en la URL existente.
Actualizar a una nueva URL
- Haz clic en el icono de Más (⋯) junto a la referencia.
- Haz clic en Editar.
- Introduce la nueva URL en el campo URL .
- Haz clic en Actualizar.
Regenerar a partir de un archivo de especificaciones
- Haz clic en el icono de Más (⋯) junto a la referencia.
- Haz clic en Editar.
- Sube el último archivo de especificaciones en formato JSON, YAML o YML.
- Haz clic en Actualizar.
Resincronización vía CI/CD
Si tu referencia de API se configuró con el flujo CI/CD, la resincronización ocurre automáticamente como parte de tu pipeline cada vez que cambia tu especificación. También puedes activar una resincronización manual usando el apidocs:resync comando:
d360 apidocs:resync \
--apiKey=YOUR_API_KEY \
--userId=YOUR_USER_ID \
--apiReferenceId=YOUR_API_REFERENCE_ID \
--path=PATH_TO_SPEC_FILE
Para detalles completos sobre cómo configurar y gestionar el flujo CI/CD, véase el artículo sobre integración CI/CD .
Resincronización automática vs manual
| Método de creación | Resincronización automática | Resincronización manual |
|---|---|---|
| Carga de archivo | No disponible | Sí, a través de Editar en el portal |
| Importación de URL | No disponible | Sí, mediante Resincronización o Edición en el portal |
| Flujo CI/CD | Sí, se ejecuta como parte de tu pipeline | Sí, ejecuta el comando CLI manualmente |
Si generaste la documentación de tu API a partir de una URL o un archivo, no se actualizará automáticamente. Para que la documentación se actualice automáticamente, integra con el flujo CI/CD.
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 especificaciones de forma segura:
- Sube el archivo de especificaciones actualizado en la ventana de referencia Editar API .
- Si se elimina algún endpoint, se muestra una advertencia. Haz clic en Mostrar endpoints eliminados para revisar la lista de endpoints afectados.
- Selecciona la casilla Confirmar para continuar para reconocer la eliminación.
- 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.
Si estás usando el endpoint de la API de resync de forma programática, envía ForceImport = false para previsualizar la lista de endpoints que se eliminarán sin continuar. Envía ForceImport = true para confirmar y procede.
Mantener la documentación en borrador
Después de subir o volver a sincronizar una especificación, puedes mantener la documentación resultante en modo borrador en lugar de publicarla inmediatamente.
- En la ventana de confirmación de publicación, haz clic en Cerrar en lugar de Publicar. Todos los artículos generados permanecerán en modo borrador.
- Los borradores de artículos son visibles en el panel de Categorías y Artículos del portal, pero no son accesibles para los lectores en la página de la base de conocimiento.
- Puedes revisar, editar y añadir contenido personalizado a los borradores de los artículos antes de publicarlos.
Categorías anidadas
Document360 soporta hasta tres niveles de subcategorías en el espacio de trabajo de documentación de la API. Las categorías se crean en función de las definiciones de etiquetas en tu archivo de especificaciones.
Para crear categorías anidadas, utiliza el > símbolo en tus etiquetas OpenAPI:
tags:
- name: "Pets > Details"
Esto crea una Pets categoría con una Details subcategoría en su interior. Esta estructura se conserva durante la resincronización.
Si tu especialización define más de tres niveles de anidamiento, cualquier categoría superior al tercer nivel se coloca en el tercer nivel.
Ordenamiento por categorías
El orden en que aparecen las categorías en tu documentación coincide con el orden de etiquetas definido en tu archivo de especificaciones. Para cambiar el orden de categorías, reordena el tags array en tu especificación y vuelve a sincronizar.
Opciones de categoría
Al hacer clic derecho en una categoría en el panel de Categorías y Artículos te da las siguientes opciones:
| Opción | Qué hace |
|---|---|
| Renombración | Renombra la categoría. |
| Artículo | Añade un nuevo artículo o subartículo dentro de la categoría. |
| Subcategoría | Añade una subcategoría dentro de la categoría. |
| Cambio de tipo | Cambia el tipo de categoría. |
| Configurar carpeta de unidades | Vincula la categoría a una carpeta de Document360 Drive. |
| Editar referencia API | Actualiza el archivo de especificaciones o la URL para la referencia de la API. |
| Descargar la fuente original de la API | Descarga el archivo de especificaciones actual. |
| Publicar | Publica todos los borradores de artículos en la categoría. |
| Seguridad | Configura quién puede acceder a la categoría desde el portal y la página de la Base de Conocimiento. |
Puedes mover los artículos de endpoint entre subcarpetas dentro de la misma carpeta de referencia de API. No es posible mover un artículo de endpoint de una carpeta de referencia de API a otra carpeta de referencia de API.
Preguntas frecuentes
¿Con qué frecuencia se resincroniza automáticamente una referencia de API?
Las referencias de API creadas a partir de una URL o archivo no se resincronizan automáticamente. Deben actualizarse manualmente a través del portal. Para habilitar actualizaciones automáticas, integra con el flujo CI/CD.
¿Puedo mover un artículo específico de endpoint API de una carpeta de referencia API a otra?
No. Puedes mover los artículos de endpoint entre subcarpetas dentro de la misma carpeta de referencia de API, pero no entre diferentes carpetas de referencia de API.
¿Puede un artículo de documentación de API tener la misma URL que un artículo de la Knowledge Base?
No. Los artículos de documentación de API y los artículos de la Knowledge Base no pueden compartir la misma URL. Sin embargo, pueden existir bajo el mismo subdominio.
¿Puedo mantener la documentación generada en modo borrador?
Sí. Después de subir una especificación, haz clic en Cerrar en lugar de Publicar en la ventana de confirmación. Todos los artículos generados se guardarán en modo borrador.
¿Cuántos niveles de categorías están soportados?
El espacio de trabajo de documentación de la API soporta hasta tres niveles de subcategorías. Niveles adicionales se colapsan al tercer nivel.
¿Puedo crear carpetas anidadas automáticamente desde el archivo de especificaciones?
Sí, usando el > símbolo en las etiquetas OpenAPI (por ejemplo, Pets > Details). Esto crea una estructura jerárquica que se conserva durante la resincronización.
¿Pueden los lectores acceder al sitio de la base de conocimientos durante la inactividad del portal Document360?
Sí. Las llamadas GET de la API del Cliente se ejecutan de forma independiente del portal Document360, por lo que los lectores pueden seguir accediendo al sitio durante el mantenimiento programado o el tiempo de inactividad del portal.