Integración CI/CD

El flujo CI/CD te permite mantener la documentación de tu API sincronizada automáticamente con tu archivo de especificaciones. En lugar de subir manualmente una nueva especificación cada vez que cambia tu API, integras la CLI de Document360 (d360) en tu pipeline existente. Cuando cambia tu especificación, la tubería se ejecuta y tu documentación se actualiza automáticamente.

Requisitos

Antes de configurar el flujo CI/CD, asegúrese de lo siguiente:

• La última versión de Node.js está instalada en el sistema que ejecuta la pipeline.
• Tienes disponible tu clave API de Document360, ID de usuario y ID de referencia de API .
• Tu archivo de especificaciones es accesible ya sea como una ruta local o como una URL alojada desde el entorno de la pipeline.

Encontrar tu clave de API, ID de usuario e ID de referencia API

Document360 no proporciona pantallas de búsqueda independientes separadas para estos valores. En su lugar, los tres están pre-rellenados para ti dentro de un comando CLI listo para ejecutar, disponible en dos lugares:

• Al crear una nueva referencia: En la ventana de referencia de la Nueva API, seleccione el botón de radio CI/CD Flow .
• Para una referencia existente: Abre la referencia, haz clic en Editar referencia API y luego selecciona Mostrar detalles en el banner "También puedes actualizar y resincronizar la Referencia API usando nuestro paquete D360 npm".

Cualquiera de las dos opciones muestra el comando completo apidocs:resync con --userId, --apiReferenceId, y --apiKey ya rellenado.

Instalación de la CLI de Document360

La herramienta CLI de Document360 se distribuye como un paquete npm llamado d360. Instálalo globalmente:

npm install d360 -g

Configuración inicial: creación de una nueva referencia de API mediante CLI

Si configuras CI/CD para una nueva referencia de API, puedes generar la importación inicial directamente desde la CLI.

1. En el portal de la Base de conocimiento, navega a la documentación { } de la API en la barra de navegación de la izquierda.
2. Haz clic en el desplegable Crear y selecciona Nueva API.
3. En la ventana de referencia de la Nueva API, seleccione el botón de radio CI/CD Flow .
4. Copia el comando completo de la CLI que aparece en la ventana.
5. Sustituye el --path valor en el comando copiado por la ruta hacia tu archivo de especificaciones.

Archivo local:

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

URL alojada:

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

6. Pega el comando actualizado en tu terminal y pulsa Enter.

Document360 sube el archivo de especificaciones y genera la referencia de la API.

Resincronización de una referencia de API existente

Una vez creada una referencia de API, usa el apidocs:resync comando para actualizarla cuando cambie tu especificación. Este es el comando que ejecutarás en tu pipeline CI/CD.

d360 apidocs:resync \
  --apiKey=YOUR_API_KEY \
  --userId=YOUR_USER_ID \
  --apiReferenceId=YOUR_API_REFERENCE_ID \
  --path=PATH_TO_SPEC_FILE

Sustituye los valores provisionales:

Manejo de múltiples archivos de especificaciones (monorepo)

La CLI no ofrece una opción por lotes — --path acepta un único archivo de especificación o URL.

Para mantener varios servicios sincronizados desde un mismo repositorio, ejecuta un comando separado apidocs:resync para cada servicio, asignando a cada uno su propio --apiReferenceId y --path.

Detección de fallos en tu pipeline

Actualmente, la CLI no utiliza su código de salida para indicar si una importación o resincronización ha tenido éxito. Un resincronización fallida — por ejemplo, "¡Resincronización fallida! Encontramos N alertas" o un error de API — se imprime en la consola, pero el proceso sigue saliendo con código 0. Como resultado, el paso de la tubería parecerá pasar incluso cuando la especificación no se ha actualizado.

Para detectar fallos de forma fiable, inspecciona la salida de la consola del comando en busca de mensajes de fallo y falla tú mismo el paso si se encuentra uno, en lugar de depender del código de salida.

Validación sin publicar

No hay bandera --dry-run . Para validar un archivo de especificaciones sin hacer ningún cambio en la referencia de tu API, usa el apidocs:validate comando:

d360 apidocs:validate --apiKey=YOUR_API_KEY --path=PATH_TO_SPEC_FILE

Esto informa de cualquier error o advertencia en la especificación sin publicar ni actualizar la referencia. Nótese que apidocs:validate toma solo --apiKey y --path — no requiere --userId ni --apiReferenceId. Ejecutarlo como paso previo apidocs:resync es una buena forma de detectar problemas de especificaciones temprano en una pipeline.

Gestión de tu clave API en CI

Tu clave API es una credencial secreta. No lo codifiques directamente en los archivos de configuración de tu pipeline ni lo commitas en control de versiones.

Guárdalo como variable de entorno o secreto en tu plataforma de CI y haz referencia en el comando:

d360 apidocs:resync \
  --apiKey=$DOCUMENT360_API_KEY \
  --userId=$DOCUMENT360_USER_ID \
  --apiReferenceId=$API_REFERENCE_ID \
  --path=./openapi.yaml

Ejemplos de oleoductos

Acciones en GitHub

Crea .github/workflows/api-docs.yml:

name: Sync API docs to Document360
on:
  push:
    branches: [main]
    paths: ['openapi.yaml']
jobs:
  resync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'
      - run: npm install d360 -g
      - name: Resync to Document360
        shell: bash
        run: |
          set +e
          d360 apidocs:resync \
            --apiKey="${{ secrets.DOCUMENT360_API_KEY }}" \
            --userId="${{ secrets.DOCUMENT360_USER_ID }}" \
            --apiReferenceId="${{ secrets.API_REFERENCE_ID }}" \
            --path=./openapi.yaml \
            --force 2>&1 | tee resync.out
          grep -qi "Resync Successful" resync.out \
            || { echo "::error::Document360 resync failed"; exit 1; }

Almacenar DOCUMENT360_API_KEY, DOCUMENT360_USER_ID, y API_REFERENCE_ID como secretos del repositorio, usando los valores del comando CLI precompletado.

GitLab CI

Añadir lo siguiente a:.gitlab-ci.yml

stages:
  - sync

sync-api-docs:
  stage: sync
  image: node:lts
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      changes: [openapi.yaml]
  script:
    - npm install d360 -g
    - |
      set +e
      d360 apidocs:resync \
        --apiKey="$DOCUMENT360_API_KEY" \
        --userId="$DOCUMENT360_USER_ID" \
        --apiReferenceId="$API_REFERENCE_ID" \
        --path=./openapi.yaml \
        --force 2>&1 | tee resync.out
      grep -qi "Resync Successful" resync.out || { echo "Document360 resync failed"; exit 1; }

Almacena DOCUMENT360_API_KEY, DOCUMENT360_USER_ID, y API_REFERENCE_ID como variables enmascaradas de CI/CD en Configuración > CI/ CD > Variables.

Soporte de Webhook en CI/CD

Los Webhooks definidos en tu especificación OpenAPI 3.1 están totalmente soportados en operaciones de resincronización CI/CD. Cuando se ejecuta una resincronización, las definiciones de webhook se actualizan junto con el resto del contenido de la especificación.

Enlaces útiles

• Paquete D360 npm
• Código fuente de d360