CI/CDとの統合

OpenAPI仕様の更新をGitBookで自動化する方法を学ぶ

GitBook は、OpenAPI 仕様の管理に既に使用している任意の CI/CD パイプラインと連携できます。GitBook CLI を使用することで、API リファレンスの更新を自動化できます。

仕様ファイルをアップロードする

OpenAPI 仕様が CI プロセス中に生成される場合、ビルド環境から直接アップロードできます：

# GitBook の API トークンを環境変数として設定
export GITBOOK_TOKEN=<api-token>

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

新しいソース URL を設定するか更新をトリガーする

OpenAPI 仕様が URL にホストされている場合、GitBook は自動的に更新をチェックします。リリース後などに更新を強制するには、次を実行します：

# GitBook の API トークンを環境変数として設定
export GITBOOK_TOKEN=<api-token>

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

GitHub Actions で仕様を更新する

OpenAPI 仕様を公開するワークフローを設定する場合、リポジトリで次の手順を完了してください：

1. リポジトリで「Settings → Secrets and variables → Actions」に移動します。

2. シークレットを追加： GITBOOK_TOKEN （あなたの GitBook API トークン）。

3. 変数を追加する（またはワークフローにハードコードする）：

   • GITBOOK_SPEC_NAME → GitBook 内のあなたの仕様の名前

   • GITBOOK_ORGANIZATION_ID → あなたの GitBook 組織 ID

4. ワークフローファイルを次の名前で保存： .github/workflows/gitbook-openapi-publish.yml.

5. 変更を “main” にプッシュする（またはワークフローを手動で実行する）。

その後、このアクションを使用して仕様を更新できます：

.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:
      # 必須のシークレット
      GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
      # 可能ならリポジトリ/組織の変数を優先；必要ならインライン文字列にフォールバック
      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>