--- title: "CI/CD-Integration" slug: "ci-cd-integration" updated: 2026-06-15T13:16:59Z published: 2026-06-15T13:16:59Z canonical: "docs.document360.com/ci-cd-integration" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.document360.com/llms.txt > Use this file to discover all available pages before exploring further. # CI/CD-Integration Der CI/CD-Fluss ermöglicht es dir, deine API-Dokumentation automatisch mit deiner Spezifikationsdatei synchron zu halten. Anstatt bei jeder Änderung Ihrer API manuell eine neue Spezifikation hochzuladen, integrieren Sie die Document360 CLI (`d360`) in Ihre bestehende Pipeline. Wenn sich deine Spezifikation ändert, läuft die Pipeline und deine Dokumentation aktualisiert sich automatisch. --- ## Anforderungen Bevor Sie den CI/CD-Fluss einrichten, stellen Sie Folgendes sicher: - Die neueste Version von **Node.js** wird auf dem System installiert, das die Pipeline ausführt. - Sie haben Ihren **Document360-API-Schlüssel**, **Ihre Benutzer-ID** und Ihre **API-Referenz-ID** verfügbar. - Deine Spezifikationsdatei ist entweder als lokaler Dateipfad oder als gehostete URL innerhalb der Pipeline-Umgebung zugänglich. HINWEIS Wenn Sie mit Node.js Installation nicht vertraut sind, lesen Sie die [offizielle Node.js Dokumentation](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) für Einrichtungsanweisungen. ### Finden Ihres API-Schlüssels, Ihrer Benutzer-ID und Ihrer API-Referenz-ID Document360 bietet keine separaten, eigenständigen Nachschlagebildschirme für diese Werte an. Stattdessen werden alle drei in einem einsatzbereiten CLI-Befehl vorab ausgefüllt, der an zwei Stellen verfügbar ist: - **Beim Erstellen einer neuen Referenz:** Im Referenzfenster für neue APIs wählen Sie den **CI/CD-Flow-Funkknopf** . - **Als bestehende Referenz:** Öffnen Sie die Referenz, klicken Sie **auf API-Referenz bearbeiten** und wählen Sie dann **Details anzeigen** auf dem *Banner "Sie können die API-Referenz auch aktualisieren und neu synchronisieren".* Beide Optionen zeigen den vollständigen `apidocs:resync` Befehl mit `--userId`, `--apiReferenceId`, und `--apiKey` bereits ausgefüllt. WICHTIG! Das API-Token **, das unter** Settings > **Knowledge Base Portal** > **API-Token** zu finden ist, ist für die Document360 Customer (öffentliche) API und kann nicht mit dem d360 CI/CD-Flow verwendet werden. Verwenden Sie immer den `--apiKey` Wert aus dem oben ausgefüllten CLI-Befehl. --- ## Installation der Document360-CLI Das CLI-Tool Document360 wird als npm-Paket mit dem Namen `d360`ausgeliefert. Installieren Sie es global: ``` npm install d360 -g ``` HINWEIS Du musst diesen Installationsbefehl nur einmal ausführen. Wenn die CLI bereits im System installiert ist, überspringen Sie diesen Schritt. --- ## Anfängliche Einrichtung: Erstellung einer neuen API-Referenz über CLI Wenn du CI/CD für eine neue API-Referenz einrichtest, kannst du den initialen Import direkt aus der CLI generieren. 1. Im Knowledge Base-Portal navigieren Sie in der linken Navigationsleiste zur **API-Dokumentation**`{ }`. 2. Klicken Sie auf das **Dropdown-Menü Erstellen** und wählen **Sie Neue API.** 3. Im Referenzfenster für neue APIs wählen Sie den **CI/CD-Flow-Funkknopf** . 4. Kopiere den vollständigen CLI-Befehl, der im Fenster angezeigt wird. 5. Ersetze den `--path` Wert im kopierten Befehl durch den Pfad zu deiner Spezifikationsdatei. **Lokale Datei:** ``` --path=/Users/yourname/projects/api/openapi.yaml ``` **Gehostete URL:** ``` --path=https://example.com/api/openapi.yaml ``` 1. Fügen Sie den aktualisierten Befehl in Ihr Terminal ein und drücken Sie Enter. Document360 lädt die Spezifikationsdatei hoch und generiert die API-Referenz. --- ## Neusynchronisierung einer bestehenden API-Referenz Sobald eine API-Referenz erstellt wurde, verwenden Sie den `apidocs:resync` Befehl, um sie zu aktualisieren, wenn sich Ihre Spezifikation ändert. Das ist der Befehl, den du in deiner CI/CD-Pipeline ausführen wirst. ``` d360 apidocs:resync \  --apiKey=YOUR_API_KEY \  --userId=YOUR_USER_ID \  --apiReferenceId=YOUR_API_REFERENCE_ID \  --path=PATH_TO_SPEC_FILE ``` Ersetzen Sie die Platzhalterwerte: | Parameter | Was soll ich hier platzieren | | --- | --- | | `--apiKey` | Ihr Document360-API-Schlüssel | | `--userId` | Ihre Document360-Benutzer-ID | | `--apiReferenceId` | Die ID der API bezieht sich auf das Aktualisieren | | `--path` | Vollständiger Pfad zu deiner Spezifikationsdatei oder eine URL, die darauf verweist | HINWEIS Alle benutzerdefinierten Inhalte, die du zu einzelnen Endpunkt-Artikeln hinzugefügt hast, werden behalten, wenn eine Neusynchronisation ausgeführt wird. Nur der von Specs generierte Inhalt wird aktualisiert. ### Umgang mit mehreren Spezifikationsdateien (Monorepo) Die CLI bietet keine Batch-Option – `--path` sie akzeptiert eine einzelne Spezifikationsdatei oder URL. Um mehrere Services aus einem Repository synchron zu halten, führe für jeden Service einen separaten `apidocs:resync` Befehl aus, wobei jeder seinen eigenen `--apiReferenceId` und `--path`. WICHTIG Passe `--path` immer explizit in einem Monorepo. Wenn sie weggelassen wird, wählt die CLI automatisch die erste gefundene Spezifikationsdatei aus, die möglicherweise nicht die ist, die du beabsichtigst. ### Fehler in Ihrer Pipeline erkennen Die CLI verwendet derzeit ihren Ausgangscode nicht, um anzuzeigen, ob ein Import oder eine Neusynchronisation erfolgreich war. Ein fehlgeschlagener Resync – zum Beispiel: "Resync fehlgeschlagen! Wir haben N Warnung(en)" oder einen API-Fehler gefunden – wird auf die Konsole ausgedruckt, aber der Prozess beendet trotzdem mit Code `0`. Infolgedessen scheint der Pipeline-Schritt auch dann zu bestehen, wenn die Spezifikation nicht aktualisiert wurde. Um Fehler zuverlässig zu erkennen, überprüfen Sie die Konsolenausgabe des Befehls auf Fehlermeldungen und scheitern Sie selbst, falls eine gefunden wird, anstatt sich auf den Exit-Code zu verlassen. ### Validierung ohne Veröffentlichung Es gibt keine `--dry-run` Flagge. Um eine Spezifikationsdatei zu validieren, ohne Änderungen an Ihrer API-Referenz vorzunehmen, verwenden Sie den `apidocs:validate` Befehl: ``` d360 apidocs:validate --apiKey=YOUR_API_KEY --path=PATH_TO_SPEC_FILE ``` Dies meldet alle Fehler oder Warnungen in der Spezifikation, ohne die Referenz zu veröffentlichen oder zu aktualisieren. Beachten Sie, dass `apidocs:validate` nur `--apiKey` und nimmt — `--path` es benötigt `--userId` nicht oder `--apiReferenceId`. Es als Schritt vorher `apidocs:resync` laufen zu lassen, ist eine gute Möglichkeit, Spezifikationsprobleme frühzeitig in einer Pipeline zu erkennen. --- ## Verwaltung Ihres API-Schlüssels in CI Ihr API-Schlüssel ist eine geheime Zugangsberechtigung. Programmieren Sie sie nicht in Ihren Pipeline-Konfigurationsdateien fest und committen Sie sie nicht in die Versionskontrolle. Speichere es als Umgebungsvariable oder Geheimnis in deiner CI-Plattform und referenziere es im Befehl: ``` d360 apidocs:resync \  --apiKey=$DOCUMENT360_API_KEY \  --userId=$DOCUMENT360_USER_ID \  --apiReferenceId=$API_REFERENCE_ID \  --path=./openapi.yaml ``` WICHTIG! Wenn Sie Ihren API-Schlüssel im Document360-Portal neu generieren, wird der alte Schlüssel sofort ungültig. Aktualisiere das Geheimnis auf deiner CI-Plattform vor dem nächsten Pipeline-Lauf, sonst schlägt dein Resync fehl. --- ## Pipeline-Beispiele ### GitHub-Aktionen Erstellen `.github/workflows/api-docs.yml`Sie : ``` 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; } ``` Speichere `DOCUMENT360_API_KEY`, `DOCUMENT360_USER_ID`, und `API_REFERENCE_ID` als Repository-Geheimnisse, wobei die Werte des vorgefüllten CLI-Befehls verwendet werden. ### GitLab CI Fügen Sie Folgendes hinzu:`.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; } ``` Speichere `DOCUMENT360_API_KEY`, `DOCUMENT360_USER_ID`, und `API_REFERENCE_ID` als maskierte CI/CD-Variablen unter **Einstellungen** > **CI/CD** > **Variablen**. HINWEIS GitLab kann keine Werte mit Bindestrichen maskieren, daher werden Benutzer-ID und API-Referenz-ID unmaskiert gespeichert. --- ## Webhook-Unterstützung in CI/CD Webhooks, die in Ihrer OpenAPI 3.1-Spezifikation definiert sind, werden in CI/CD-Resync-Operationen vollständig unterstützt. Wenn ein Resync ausgeführt wird, werden Webhook-Definitionen zusammen mit dem restlichen Spezifikationsinhalt aktualisiert. --- ## Hilfreiche Links - [d360 npm-Paket](https://www.npmjs.com/package/d360) - [d360-Quellcode](https://github.com/document360/d360)