CI/CD-integratie

De CI/CD-flow laat je je API-documentatie automatisch synchroon houden met je specificatiebestand. In plaats van elke keer handmatig een nieuwe specificatie te uploaden wanneer je API verandert, integreer je de Document360 CLI (d360) in je bestaande pipeline. Wanneer je specificatie verandert, draait de pipeline en wordt je documentatie automatisch bijgewerkt.

Vereisten

Voordat je de CI/CD-flow opzet, zorg voor het volgende:

• De nieuwste versie van Node.js is geïnstalleerd op het systeem dat de pijplijn draait.
• Je hebt je Document360 API-sleutel, gebruikers-ID en API-referentie-ID beschikbaar.
• Je spec-bestand is toegankelijk als een lokaal bestandspad of als een gehoste URL binnen de pipeline-omgeving.

Je API-sleutel, gebruikers-ID en API-referentie-ID vinden

Document360 biedt geen aparte standup-screens voor deze waarden. In plaats daarvan worden alle drie vooraf voor je ingevuld in een kant-en-klaar CLI-commando, beschikbaar op twee plaatsen:

• Bij het aanmaken van een nieuwe referentie: Selecteer in het New API-referentievenster de CI/CD Flow-radioknop .
• Voor een bestaande referentie: Open de referentie, klik op API-referentie bewerken en kies vervolgens op de banner "Je kunt ook de API-referentie bijwerken en opnieuw synchroniseren met ons D360 npm-pakket".

Beide opties tonen het volledige apidocs:resync commando met --userId, --apiReferenceId, en --apiKey al ingevuld.

Het installeren van de Document360 CLI

De Document360 CLI-tool wordt verspreid als een npm-pakket genaamd d360. Installeer het globaal:

npm install d360 -g

Initiële opstelling: een nieuwe API-referentie aanmaken via CLI

Als je CI/CD opstelt voor een nieuwe API-referentie, kun je de initiële import direct genereren vanuit de CLI.

1. Navigeer in het kennisbankportaal naar API-documentatie { } in de linker navigatiebalk.
2. Klik op de keuzemenu Aanmaken en selecteer Nieuwe API.
3. Selecteer in het New API-referentievenster de CI/CD Flow-radioknop .
4. Kopieer het volledige CLI-commando dat in het venster wordt weergegeven.
5. Vervang de --path waarde in het gekopieerde commando door het pad naar je specificatiebestand.

Lokaal bestand:

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

Gehoste URL:

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

6. Plak het bijgewerkte commando in je terminal en druk op Enter.

Document360 uploadt het specificatiebestand en genereert de API-referentie.

Een bestaande API-referentie opnieuw synchroniseren

Zodra een API-referentie is aangemaakt, gebruik je het apidocs:resync commando om deze bij te werken wanneer je specificatie verandert. Dit is het commando dat je in je CI/CD-pijplijn uitvoert.

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

Vervang de placeholder-waarden:

Meerdere specificatiebestanden verwerken (monorepo)

De CLI biedt geen batchoptie — --path accepteert één specificatiebestand of URL.

Om meerdere services synchroon te houden vanuit één repository, voer je voor elke service een apart apidocs:resync commando uit, waarbij elke service zijn eigen --apiReferenceId en --pathkrijgt.

Fouten in je pijplijn detecteren

De CLI gebruikt momenteel zijn exitcode niet om aan te geven of een import of hersynchronisatie is geslaagd. Een mislukte resync — bijvoorbeeld: "Resync mislukt! We hebben N waarschuwingen gevonden" of een API-fout — wordt naar de console geprint, maar het proces sluit nog steeds af met code 0. Daardoor zal de pipeline-stap lijken te slagen, zelfs wanneer de specificatie niet is bijgewerkt.

Om fouten betrouwbaar te detecteren, inspecteer je de console-output van het commando op foutmeldingen en faal je de stap zelf als er een wordt gevonden, in plaats van te vertrouwen op de exitcode.

Valideren zonder te publiceren

Er is geen --dry-run vlag. Om een spec-bestand te valideren zonder wijzigingen aan je API-referentie aan te brengen, gebruik je het apidocs:validate commando:

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

Dit meldt eventuele fouten of waarschuwingen in de specificatie zonder de referentie te publiceren of bij te werken. Let op dat apidocs:validate alleen --apiKey en --path neemt — het vereist --userId geen of --apiReferenceId. Het als stap vooraf apidocs:resync draaien is een goede manier om specificatieproblemen vroeg in een pijplijn te ontdekken.

Je API-sleutel beheren in CI

Je API-sleutel is een geheim inloggegevens. Hardcode het niet in je pipelineconfiguratiebestanden en commit het niet in de source control.

Sla het op als een omgevingsvariabele of geheim in je CI-platform en verwijs ernaar in het commando:

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

Pijpleidingvoorbeelden

GitHub-acties

Maak :.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; }

Sla , DOCUMENT360_USER_ID, en API_REFERENCE_ID als repository-geheimen op, DOCUMENT360_API_KEYmet behulp van de waarden uit het vooraf ingevulde CLI-commando.

GitLab CI

Voeg het volgende toe aan .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; }

Sla DOCUMENT360_API_KEY, DOCUMENT360_USER_ID, en API_REFERENCE_ID als gemaskeerde CI/CD-variabelen op onder Instellingen > CI/CD > Variabelen.

Webhook-ondersteuning in CI/CD

Webhooks die zijn gedefinieerd in je OpenAPI 3.1-specificatie worden volledig ondersteund in CI/CD-resyncoperaties. Wanneer een resync wordt uitgevoerd, worden webhook-definities bijgewerkt samen met de rest van de specificatie-inhoud.

Handige links

• d360 npm-pakket
• D360 broncode