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. リポジトリで、「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: 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>