CI/CD との統合

GitBook で OpenAPI スペックの更新を自動化する方法を学びましょう

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. リポジトリで、「設定 → シークレットと変数 → 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: GitBook に OpenAPI を公開

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: GitBook に仕様ファイルを公開
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <path_to_spec>