Intégration avec CI/CD

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

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

Téléverser un fichier de spécification

Si votre spécification OpenAPI est générée pendant votre processus CI, vous pouvez la téléverser 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 un rafraîchissement

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 publication), 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

Mettez à jour votre spécification avec GitHub Actions

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

1. Dans votre dépôt, allez dans « Paramètres → Secrets et variables → Actions ».
2. Ajoutez un secret : GITBOOK_TOKEN (votre jeton API GitBook).
3. Ajoutez des variables (ou codifiez-les en dur dans le workflow) :

   • GITBOOK_SPEC_NAME → le nom de votre spécification dans GitBook
   • GITBOOK_ORGANIZATION_ID → l’identifiant de votre organisation GitBook
4. Enregistrez le fichier du workflow sous .github/workflows/gitbook-openapi-publish.yml.
5. Poussez les modifications vers « main » (ou exécutez le workflow manuellement).

Vous pouvez ensuite utiliser cette action pour mettre à jour votre spécification :

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

name: Publier OpenAPI sur GitBook

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

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      # Secret requis
      GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
      # Préférez les variables du dépôt/de l’organisation ; sinon, utilisez des chaînes en dur si vous le souhaitez
      GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}
      GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}

    steps:
      - name: Récupération du dépôt
        uses: actions/checkout@v4

      - name: Publier le fichier de spécification sur GitBook
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <path_to_spec>