---
title: "CI/CD-integratie"
slug: "ci-cd-integration"
updated: 2026-06-15T13:19:33Z
published: 2026-06-15T13:19:33Z
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-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.

 OPMERKING

Als je niet bekend bent met Node.js installatie, raadpleeg dan de [officiële Node.js documentatie](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) voor installatie-instructies.

### 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.

BELANGRIJK!

De API-token die te vinden is onder **Settings** > **Knowledge Base-portaal** > **API-tokens** is bedoeld voor de Document360 Customer (publieke) API en kan niet worden gebruikt met de d360 CI/CD-flow. Gebruik altijd de `--apiKey` waarde van het hierboven ingehaalde CLI-commando.

---

## 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
```

 OPMERKING

Je hoeft dit installatiecommando maar één keer uit te voeren. Als de CLI al op het systeem is geïnstalleerd, sla dan deze stap over.

---

## 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
```

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

| Parameter | Wat hier te plaatsen |
| --- | --- |
| `--apiKey` | Uw Document360 API-sleutel |
| `--userId` | Je Document360-gebruikers-ID |
| `--apiReferenceId` | De ID van de API verwijst naar updaten |
| `--path` | Volledig pad naar je specificatiebestand, of een URL die ernaar wijst |

 OPMERKING

Alle aangepaste content die je aan individuele endpoint-artikelen hebt toegevoegd, blijft behouden wanneer een resync wordt uitgevoerd. Alleen de door specificaties gegenereerde content wordt bijgewerkt.

### 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 `--path`krijgt.

BELANGRIJK

Altijd expliciet passen `--path` in een monorepo. Als het wordt weggelaten, selecteert de CLI automatisch het eerste spec-bestand dat het vindt, dat mogelijk niet het exemplaar is dat je bedoelt.

### 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
```

BELANGRIJK!

Als je je API-sleutel opnieuw genereert in het Document360-portaal, wordt de oude sleutel direct ongeldig. Werk het geheim bij in je CI-platform vóór de volgende pipeline-run, anders faalt je resync.

---

## 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_KEY`met 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**.

 OPMERKING

GitLab kan geen waarden maskeren die koppeltekens bevatten, dus de gebruikers-ID en API-referentie-ID worden ongemaskeerd opgeslagen.

---

## 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](https://www.npmjs.com/package/d360)
- [D360 broncode](https://github.com/document360/d360)