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.

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.

Installation der Document360-CLI

Das CLI-Tool Document360 wird als npm-Paket mit dem Namen d360ausgeliefert. Installieren Sie es global:

npm install d360 -g

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

6. 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:

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.

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

Pipeline-Beispiele

GitHub-Aktionen

Erstellen .github/workflows/api-docs.ymlSie :

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.

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
• d360-Quellcode