--- title: "Intégration CI/CD" slug: "ci-cd-integration" updated: 2026-06-15T13:16:31Z published: 2026-06-15T13:16:31Z 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. # 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. NOTE Si vous ne connaissez pas Node.js installation, consultez la [documentation officielle Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) pour les instructions d’installation. ### 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. IMPORTANT ! Le jeton API trouvé dans **Paramètres** > **portail de la base de connaissances** > **jetons API** est destiné à l’API client (publique) de Document360 et ne peut pas être utilisé avec le flux CI/CD d360. Utilisez toujours la `--apiKey` valeur de la commande CLI préremplie ci-dessus. --- ## 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 ``` NOTE Vous n’avez besoin d’exécuter cette commande d’installation qu’une seule fois. Si la ligne de ligne de ligne est déjà installée sur le système, sauter cette étape. --- ## 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 ``` 1. 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 : | Paramètre | Que mettre ici | | --- | --- | | `--apiKey` | Votre clé API Document360 | | `--userId` | Votre identifiant utilisateur Document360 | | `--apiReferenceId` | L’ID de la référence API à mettre à jour | | `--path` | Chemin complet vers votre fichier spécificateur, ou une URL y pointant | NOTE Tout contenu personnalisé que vous avez ajouté à des articles de points de terminaison individuels sera conservé lors de la resynchronisation. Seul le contenu généré par la spécification est mis à jour. ### 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`. IMPORTANT Réussissez `--path` toujours explicitement dans un monorepo. Si elle est omise, la CLI sélectionne automatiquement le premier fichier de spécifications qu’il trouve, qui n’est peut-être pas celui que vous souhaitez faire. ### 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 ``` IMPORTANT ! Si vous régénérez votre clé API dans le portail Document360, l’ancienne clé devient immédiatement invalide. Mettez à jour le secret dans votre plateforme CI avant la prochaine exécution du pipeline, sinon votre resynchronisation échouera. --- ## 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**. NOTE GitLab ne peut pas masquer les valeurs contenant des traits d’union, donc l’identifiant utilisateur et l’identifiant de référence API seront stockés sans masque. --- ## 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](https://www.npmjs.com/package/d360) - [Code source d360](https://github.com/document360/d360)