Intégration avec CI/CD

Apprenez comment automatiser la mise à jour de votre spécification OpenAPI dans GitBook

GitBook peut fonctionner avec n’importe quel pipeline CI/CD que vous utilisez déjà pour gérer votre spécification OpenAPI. En utilisant le CLI GitBook, vous pouvez automatiser les mises à jour de votre référence d’API.

Télécharger un fichier de spécification

Si votre spécification OpenAPI est générée pendant votre processus CI, vous pouvez la télécharger directement depuis votre environnement de build :

# Définissez votre jeton API GitBook comme variable d’environnement
export GITBOOK_TOKEN=<api-token>

gitbook openapi publish \
  --spec spec_name \
  --organization organization_id \
  example.openapi.yaml

Définir une nouvelle URL source ou déclencher une actualisation

Si votre spécification OpenAPI est hébergée à une URL, GitBook vérifie automatiquement les mises à jour. Pour forcer une mise à jour (par exemple après une release), exécutez :

# Définissez votre jeton API GitBook comme variable d’environnement
export GITBOOK_TOKEN=<api-token>

gitbook openapi publish \
  --spec spec_name \
  --organization organization_id \
  https://api.example.com/openapi.yaml

Mettre à jour votre spec avec GitHub Actions

Si vous configurez un workflow pour publier votre spécification OpenAPI, complétez ces étapes dans votre dépôt :

1. Dans votre repo, allez sur « Settings → Secrets and variables → Actions ».

2. Ajoutez un secret : GITBOOK_TOKEN (votre jeton API GitBook).

3. Ajoutez des variables (ou codez-les en dur dans le workflow) :

   • GITBOOK_SPEC_NAME → le nom de votre spec dans GitBook

   • GITBOOK_ORGANIZATION_ID → l’ID de votre organisation GitBook

4. Enregistrez le fichier de workflow sous .github/workflows/gitbook-openapi-publish.yml.

5. Poussez les modifications sur « main » (ou exécutez le workflow manuellement).

Vous pouvez ensuite utiliser cette action pour mettre à jour votre spec :

.github/workflows/gitbook-openapi-publish.yml

name: Publish OpenAPI to GitBook

on:
  push:
    branches: [ "main" ]
    paths:
      - "**/*.yaml"
      - "**/*.yml"
      - "**/*.json"
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      # Required secret
      GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
      # Prefer repo/org variables; fallback to inline strings if you like
      GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}
      GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Publish spec file to GitBook
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <path_to_spec>