Empezando con la documentación de la API

Esta guía te guía para publicar tu primera referencia de API en Document360, desde la subida de tu archivo de especificaciones a un portal interactivo para desarrolladores en vivo.

Al final de este artículo tendrás:

• Una referencia de API generada a partir de tu especificación OpenAPI
• Tus endpoints son visibles y navegables por los desarrolladores
• La consola interactiva Try It! lista para pruebas en tiempo real de la API

Requisitos previos

Antes de empezar, asegúrate de tener:

• Una cuenta Document360 en un plan Profesional, Empresarial o Empresarial.
• Un archivo de especificación de API en uno de estos formatos: OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 o Postman Collection. Los tipos de archivo aceptados son JSON, YAML o YML.
• Acceso al portal de la base de conocimiento con permisos para crear contenido.

Navega al espacio de trabajo de documentación de la API

1. Inicia sesión en Document360 y abre tu proyecto en el portal de la Base de conocimientos.
2. En la barra de navegación de la izquierda, haz clic en documentación { }de la API. Esto abre el espacio de trabajo dedicado de la API, separado de tu base de conocimiento estándar.
3. En la barra de navegación superior, haz clic en el desplegable Crear y selecciona Nueva API. Esto abre la ventana de referencia de la nueva API.

Elige cómo importar tu especificación

Document360 soporta dos formas de importar tu archivo de especificaciones: subida de archivos e importación de URLs. El flujo CI/CD no es un método de importación separado; Es una forma de automatizar cualquiera de estos dos métodos para que tu documentación se actualice automáticamente cada vez que cambie tu especificación.

Sube tu especificación

Sube un archivo

1. En la ventana de referencia de la nueva API, selecciona la opción de definición de la API de Subir .
2. Haz clic en Subir desde mi dispositivo o arrastrar y soltar tu archivo. Formatos soportados: JSON, YAML, YML.
3. Document360 analiza el archivo y genera automáticamente la referencia de la API. Si se detectan advertencias, aparece una sección de Alertas y Advertencias — amplíala para revisarlas. Puedes ver los detalles completos más adelante en la sección de Registros.
4. Haz clic en Nueva referencia de API para continuar.

Importar desde una URL

1. En la ventana de referencia de la nueva API, selecciona la opción Crear desde URL y haz clic en Siguiente.
2. Introduce la URL que apunta a tu archivo de especificación de OpenAPI en el campo URL.
3. Document360 recoge y procesa la especificación. Si se detectan advertencias, estarán disponibles en la sección de Registros tras la importación.
4. Haz clic en Añadir referencia API para continuar.

Utilizar el flujo CI/CD

1. En la ventana de referencia de la nueva API, selecciona la opción CI/CD Flow .
2. Copia el comando CLI completo que aparece en la ventana.
3. En el comando copiado, reemplaza el --path valor por el camino completo hacia tu archivo de especificaciones local o por una URL válida que apunte a él. Por ejemplo:

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

O una URL:

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

4. Pega el comando actualizado en tu terminal y pulsa Enter. Document360 sube tu especificación y genera la documentación de la API.

¿No hay archivo de especificaciones? Utiliza la API de la tienda de mascotas de ejemplo

Si no tienes un archivo de especificaciones listo, selecciona Probar el archivo API de la tienda de mascotas cuando se lo solicite. Document360 creará automáticamente una referencia de API de ejemplo en modo borrador. Puedes explorarlo y luego reemplazarlo por tu propia especialización más adelante.

Revisar alertas y advertencias

Tras subir tu especificación, Document360 te muestra un resumen de cuántas categorías y artículos se crearon, junto con cualquier alerta o advertencia detectada en tu archivo.

• Las alertas y advertencias significan que la especificación fue importada, pero algunos elementos pueden no mostrarse como se espera. Puedes consultar todos los detalles en la sección de Registros: ve a tu referencia de API, haz clic en el icono Más (⋯) y selecciona Registros.
• Los errores significan que la importación falló. La causa más común es un formato de archivo no compatible o una URL inválida. Reemplaza el archivo o corrige la URL y vuelve a intentarlo.

Publica tu referencia de API

Después de que tu especificación haya sido procesada correctamente:

1. Una ventana de confirmación muestra el número de categorías y artículos creados. Haz clic en Publicar para poner la referencia de la API activa.
2. Si quieres revisar el contenido antes de publicarlo, haz clic en Cerrar. Tu referencia API se guarda en modo borrador y es visible en el panel de Categorías y Artículos.

Configura la autenticación para Try It!

La consola Try It! permite a los desarrolladores probar tus endpoints API directamente desde la documentación. Para que funcione correctamente, el método de autenticación debe estar definido en tu especificación y configurado en Document360.

Document360 soporta los siguientes métodos de autenticación:

OAuth2 y OpenID Connect: configuración adicional

Al usar OAuth2 o OpenID Connect, se requieren dos ajustes:

• Redirigir URI — Configura esto en tu proveedor OAuth como domain/oauth. Por ejemplo: https://apidocs.yourdomain.com/oauth.
• Renovación silenciosa — Document360 actualiza automáticamente el token de autorización en segundo plano durante las sesiones activas de Prueba!, por lo que los usuarios no necesitan volver a autenticarse manualmente.

Establecer acceso y privacidad del lector

Controla quién puede ver tu referencia de API publicada configurando la configuración de acceso del lector.

Para configurar el acceso al lector, navega a Configuración > Usuarios y Permisos > Acceso al lector en el portal de la Base de Conocimiento y localiza el espacio de trabajo de documentación de tu API.