Intégration CI/CD

Le flux CI/CD vous permet de garder votre documentation API automatiquement synchronisée avec votre fichier de spécifications. Au lieu de télécharger manuellement une nouvelle spécification à chaque changement d’API, vous intégrez la CLI de Document360 (d360) dans votre pipeline existant. Lorsque votre spécification change, le pipeline s’exécute et votre documentation se met à jour automatiquement.

Exigences

Avant de configurer le flux CI/CD, assurez-vous des éléments suivants :

• La dernière version de Node.js est installée sur le système qui exécute le pipeline.
• Vous avez votre clé API Document360, votre identifiant utilisateur et votre identifiant de référence API disponibles.
• Votre fichier de spécification est accessible soit en chemin local, soit en URL hébergée depuis l’environnement pipeline.

Trouver votre clé API, votre identifiant utilisateur et votre identifiant de référence API

Document360 ne fournit pas d’écrans de recherche indépendants séparés pour ces valeurs. À la place, les trois sont pré-remplies pour vous dans une commande CLI prête à l’exécution, disponible à deux endroits :

• Lors de la création d’une nouvelle référence : Dans la fenêtre de référence de la nouvelle API, sélectionnez le bouton radio CI/CD Flow .
• Pour une référence existante : Ouvrez la référence, cliquez sur Modifier la référence API, puis sélectionnez Afficher les détails sur la bannière « Vous pouvez également mettre à jour et resynchroniser la référence API en utilisant notre package D360 npm ».

Chacune des options affiche la commande complète apidocs:resync avec --userId, --apiReferenceId, et --apiKey déjà remplie.

Installation de la ligne de commande Document360

L’outil CLI Document360 est distribué sous forme de package npm nommé d360. Installez-le globalement :

npm install d360 -g

Configuration initiale : création d’une nouvelle référence API via CLI

Si vous configurez CI/CD pour une nouvelle référence API, vous pouvez générer l’importation initiale directement depuis la CLI.

1. Dans le portail de la base de connaissances, allez jusqu’à la documentation { } de l’API dans la barre de navigation de gauche.
2. Cliquez sur le menu déroulant Créer et sélectionnez Nouvelle API.
3. Dans la fenêtre de référence de la nouvelle API, sélectionnez le bouton radio CI/CD Flow .
4. Copiez la commande CLI complète affichée dans la fenêtre.
5. Remplacez la --path valeur dans la commande copiée par le chemin vers votre fichier de spécifications.

Fichier local :

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

URL hébergée :

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

6. Collez la commande mise à jour dans votre terminal et appuyez sur Entrée.

Document360 télécharge le fichier de spécifications et génère la référence de l’API.

Resynchronisation d’une référence d’API existante

Une fois une référence API créée, utilisez la apidocs:resync commande pour la mettre à jour lorsque votre spécification change. C’est la commande que vous exécuterez dans votre pipeline CI/CD.

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

Remplacez les valeurs de remplacement :

Gestion de plusieurs fichiers de spécifications (monorepo)

La CLI ne propose pas d’option batch — --path elle accepte un seul fichier de spécification ou une seule URL.

Pour maintenir plusieurs services synchronisés dans un même dépôt, exécutez une commande séparée apidocs:resync pour chaque service, en donnant à chacun son --apiReferenceId propre et --path.

Détection des pannes dans votre pipeline

Le CLI n’utilise actuellement pas son code de sortie pour indiquer si une importation ou une resynchronisation a réussi. Un échec de resynchronisation — par exemple, « Resynchronisation échouée ! Nous avons trouvé N alertes » ou une erreur d’API — est imprimée sur la console, mais le processus se termine toujours avec du code 0. En conséquence, l’étape du pipeline semble être passée même si la spécification n’a pas été mise à jour.

Pour détecter de manière fiable les défaillances, inspectez la sortie console de la commande à la recherche de messages d’échec et échouez vous-même à l’étape si l’une est détectée, plutôt que de vous fier au code de sortie.

Valider sans publication

Il n’y a pas --dry-run de drapeau. Pour valider un fichier de spécification sans modifier votre référence API, utilisez la apidocs:validate commande suivante :

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

Ce document signale toute erreur ou avertissement dans la spécification sans publication ni mise à jour de la référence. Notez que ne apidocs:validate prend que --apiKey et --path — il ne nécessite --userId ni --apiReferenceId. L’exécuter en tant qu’étape avant apidocs:resync est un bon moyen de détecter les problèmes de spécifications tôt dans une pipeline.

Gestion de votre clé API dans CI

Votre clé API est une certification secrète. Ne le codez pas en dur dans vos fichiers de configuration de pipeline ni ne le mettez en contrôle de version.

Stockez-le comme variable d’environnement ou secret dans votre plateforme CI et référencez-le dans la commande :

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

Exemples de pipelines

GitHub Actions

Créez .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; }

Stockez DOCUMENT360_API_KEY, DOCUMENT360_USER_ID, et API_REFERENCE_ID comme secrets du dépôt, en utilisant les valeurs de la commande CLI préremplie.

GitLab CI

Ajoutez ce qui suit à .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; }

Stockez DOCUMENT360_API_KEY, DOCUMENT360_USER_ID, et API_REFERENCE_ID comme variables CI/CD masquées sous Paramètres > CI/ CD > Variables.

Prise en charge du Webhook dans CI/CD

Les webhooks définis dans votre spécification OpenAPI 3.1 sont entièrement pris en charge dans les opérations de resynchronisation CI/CD. Lorsqu’une resynchronisation s’exécute, les définitions des webhooks sont mises à jour avec le reste du contenu des spécifications.

Liens utiles

• Package D360 npm
• Code source d360