write-openapi

GitBook OpenAPI

GitBook は OpenAPI ドキュメントを、インタラクティブでテスト可能な API リファレンスブロックに変換します。仕様を JSON または YAML で渡すと、エンドポイント、パラメーター、スキーマ、認証と、ページ内のリクエスト実行ツールが表示されます。カスタマイズの大半は GitBook の UI ではなく、仕様内の x-* 拡張で行うため、ここでの作業のほとんどは OpenAPI YAML を正しく編集することになります。

このスキルでは、仕様を GitBook に追加する方法、リファレンスページを生成する方法、ナビゲーションを構成する方法、「テスト」ランナーを動作させる方法、オペレーションとスキーマの表示を制御する方法、CI/CD から更新を自動化する方法など、すべてを扱います。

GitBook の利用方法

このスキルの大部分、つまり OpenAPI YAML/JSON 自体の編集は、転送方式に依存しません。ただし、仕様を GitBook に追加したり、リファレンスページを生成・挿入したりする場合は GitBook を利用する必要があり、その方法は複数あります。GitBook の MCP サーバーと REST API です。現在のセッションで実際に利用できるものを確認し、まず MCP を優先してください。GitBook MCP ツールがすでに接続されている場合は、そのツールが対応する操作（仕様の公開・更新、リファレンスページの生成など）には直接 API 呼び出しではなく MCP を使用します。そのための検出スクリプトは実行しないでください。利用可能なツールや MCP 接続は把握できているはずなので、その知識を活用してください。

以下の手順では、転送方式に結び付けず、「仕様を追加する」「リファレンスページを生成する」といった成果を説明しています。そのため、どの方法を使う場合にも適用できます。GitBook MCP ツールが接続されている場合は、それらを直接呼び出してください。パラメーターは各ツールのスキーマに記載されています。REST API を使用する場合、正確なエンドポイントとリクエストボディは、以下の「仕様を追加または更新する」に記載されています。

• GitBook MCP — 以下で説明する機能を網羅する読み書き用のインターフェースであり、機能を限定したものではありません。まだ接続されておらず、タスクの規模がセットアップする価値のあるもの（新しい仕様の公開、リファレンス全体の生成など。一度きりの小さな変更は除く）であれば、セットアップを提案してください：claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp（続けて /mcp を実行し、OAuth サインインを完了します。ブラウザーでの手続きを省略するには、末尾に --header "Authorization: Bearer $GITBOOK_TOKEN" を追加します）。Codex での同等のコマンド：codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp。注：これは、公開済みコンテンツのみを公開する、GitBook の別個の読み取り専用「公開ドキュメント」MCP サーバーとは異なります。
• REST API（https://api.gitbook.com/v1）— MCP が接続されていない場合、または MCP で対応していない操作を行う場合の代替手段です。すべてのリクエストで、Bearer ヘッダーに GITBOOK_TOKEN が必要です。

同じ個人用アクセストークン（https://app.gitbook.com/account/developer から取得）は、どちらでも Bearer トークンとして使用できます。MCP では、トークンを貼り付ける代わりに、より簡単な方法として OAuth もサポートしています。

トークンが必要になった場合（REST API を使う場合、または OAuth を使わずに MCP を使う場合）は、セッションの開始時にトークンがあるか確認してください：

[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"

GITBOOK_TOKEN が設定されていない場合は、ユーザーに直接尋ねてください：

1. GitBook の個人用アクセストークンが必要であることを伝え、作成するために https://app.gitbook.com/account/developer へ案内します。
2. 会話にトークンを貼り付けてもらいます。直ちに環境変数としてエクスポートし（export GITBOOK_TOKEN=<pasted value>）、応答でトークンを繰り返さないでください。
3. トークンが環境に存在することを確認するまで、API 呼び出しを行わないでください。

トークンをファイルに書き込んだり、応答で出力したり、コミットしたりしてはいけません。

GitBook CLI の gitbook openapi publish コマンド（以下の「仕様を追加または更新する」を参照）は、API および MCP と同じ基盤機能を利用します。これは独立した機能セットではなく、利便性のためのラッパーであり、同じ GITBOOK_TOKEN を使用して認証します。

まず知っておくべき重要な事実

これらはほぼすべての判断に影響するため、編集を始める前にしっかり把握してください。

• サポート対象のバージョン。 GitBook は Swagger 2.0 と OpenAPI 3.0 の仕様を受け付けます。一部の機能には、より新しいバージョンが必要です。Webhook には OpenAPI 3.1 が必要で、公式の parent タグプロパティには OpenAPI 3.2 以降が必要です（3.0.x と 3.1.x では x-parent を使用してください）。バージョンに依存する機能を使う前に、必ず仕様の openapi:／swagger: バージョンを確認してください。
• 「Test it」ランナーは Scalar を利用しています。 GitBook のプロキシ経由にしない限り、リーダーのブラウザーからリクエストを実行します。
• 仕様のソースはファイルか URL であり、更新を決めるのはそれであって、設定に使ったトランスポート（MCP、API、CLI、UI）ではありません。 URL ソースは 6 時間ごとに自動更新されます。ファイルソースは、再アップロードまたは再公開した場合にのみ変更されます。
• x-* 拡張機能は名前空間で区別され、共有仕様に安全に保持できます。 特定の拡張機能を理解しないツールはそれを無視するため、GitBook 用に計装された仕様も、ほかの場所で引き続き検証・使用できます。

何をしたいですか？

タスクに合ったセクションを確認してください。詳細なリファレンス資料として、このファイルと同じ場所に次の 2 つのファイルがあります。

• x-* 拡張機能を編集または参照する場合（各拡張機能の YAML 全体を掲載）：references/extensions.md を参照してください。
• インタラクティブランナーを一通り動作させる場合（認証方式、サーバー、CORS、プロキシ）：references/test-it-setup.md を参照してください。

タスク	移動先
仕様を GitBook に追加、または更新する	「仕様を追加または更新する」
リファレンスページを生成する、または単一のエンドポイント／スキーマをページに追加する	「API リファレンスを挿入する」
ページを分割、並べ替え、階層化し、タイトルやアイコンを設定する	「リファレンスを構成する」
「Test it」を動作させる、CORS を修正する、認証を設定する	「Test it ランナーを設定する」＋ references/test-it-setup.md
エンドポイントを試験的、非推奨、または非表示にする	「オペレーションのライフサイクルを管理する」
拡張機能の正確な名前やスコープを確認する	「拡張機能の早見表」＋ references/extensions.md
パイプラインから仕様を自動公開する	「CI/CD で自動化する」

仕様を追加または更新する

ブロックやページから参照する前に、仕様を組織に追加しておく必要があります。すべてのトランスポートで、追加と更新は同じ基盤の操作です。前述の「GitBook との通信方法」にある選択肢から、利用できるものを選んでください。どの方法を使う場合も、最初に仕様の名前／スラッグを指定してください。後から参照したり、複数の仕様を区別したりするために必要です。

GitBook MCP — 接続されている場合は、ファイルまたは URL から仕様を作成・更新するために、MCP の仕様ツールを直接使用してください。スキーマは両方のソースタイプに対応しています。

REST API — URL ソースで作成する場合：

curl -s -X POST -H "Authorization: Bearer $GITBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "<spec-name>", "source": {"url": "<hosted-url>"}}' \
  https://api.gitbook.com/v1/orgs/$ORG_ID/openapi

ファイルから作成する場合：

curl -s -X POST -H "Authorization: Bearer $GITBOOK_TOKEN" \
  -F "slug=<spec-name>" \
  -F "file=@./openapi.yaml" \
  https://api.gitbook.com/v1/orgs/$ORG_ID/openapi

既存の仕様を更新（置換）するには、同じ方法で PATCH /v1/orgs/{orgId}/openapi/{specId} に対して実行します。

GitBook CLI — 同じ API 呼び出しを行う薄いラッパーで、スクリプトやパイプラインで便利です（同じコマンドで追加と更新ができます。URL に対して実行すると、更新も強制されます）。

gitbook openapi publish --spec <spec-name> --organization <organization-id> <path-or-url>

パイプラインの自動化については「CI/CD で自動化する」を参照してください。CLI の詳細：https://gitbook.com/docs/developers/integrations/reference

GitBook アプリの UI — サイドバーの OpenAPI セクションを開き、Add specification をクリックして名前を付け、ファイルをアップロードするか、ホストされた URL を入力します。更新方法はソースによって異なります。URL ソースは 6 時間ごとに自動確認されます（すぐに取得するには Check for updates をクリックしてください。パンくずリストのアクションメニューにある Edit から、File を URL に切り替えられます）。ファイルソースの場合は、Update をクリックして新しいバージョンをアップロードする必要があります。

API リファレンスを挿入する

仕様ができたら、次のいずれかの方法でドキュメントに表示します。

ページ一式を生成する（完全なリファレンスを作成する場合におすすめです）。 対象のスペースの目次で、下部にある Add new... をクリックし、OpenAPI Reference を選択して、仕様を選んで挿入します。GitBook は仕様内のタグごとにページを作成し（「リファレンスを構成する」を参照）、必要に応じてすべてのスキーマを一覧表示するモデルページも作成します。これらのページは、仕様が更新されるたびに更新されます。

既存のページに単一の操作またはスキーマを挿入する。 / を押して OpenAPI を検索し、仕様を選んで Continue をクリックした後、埋め込む操作やスキーマを選択します。

ブロック構文。 GitBook の Markdown を直接記述する場合、OpenAPI 操作ブロックは次のようになります（内側の行にはソースが繰り返し表示されます）。

{% openapi src="https://petstore3.swagger.io/api/v3/openapi.json" path="/pet" method="post" %}
https://petstore3.swagger.io/api/v3/openapi.json
{% endopenapi %}

1 つ以上のスキーマをインラインで強調表示する場合（たとえばタグの説明内など）は、schemas ブロックを使用します。

{% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
The Pet object
{% endopenapi-schemas %}

リファレンスを構成する

GitBook は仕様の tags からナビゲーションを作成するため、リファレンスの構成は主にタグの構成で決まります。ここで説明する各拡張機能の YAML 全文は references/extensions.md にあります。

• 操作を複数のページに分割する： 操作に同じタグを付けると、タグごとにページが作成されます。

  paths:
    /pet:
      put:
        tags:
          - pet
        summary: Update an existing pet.
        operationId: updatePet
  

• ページの順序を指定する： ページの順序は、トップレベルの tags 配列内の項目の順序に従います。

  tags:
    - name: pet
    - name: store
    - name: user
  

• ページをグループにネストする： parent（OpenAPI 3.2 以降）または x-parent（3.0.x／3.1.x）を使って、タグの親タグを指定します。

  tags:
    - name: everything
    - name: pet
      x-parent: everything
    - name: store
      x-parent: everything
  

  親ページに description がない場合、GitBook はサブページへのリンクを含むカード形式のレイアウトを自動的に表示します。

• ページごとにタイトル、アイコン、説明を追加する： タグレベルの拡張機能を使用します。アイコンには任意の Font Awesome 名を指定できます（https://fontawesome.com/search）。

  tags:
    - name: pet
      x-page-title: Pet              # title in the table of contents and page header
      x-page-icon: dog               # icon in the ToC and next to the title
      x-page-description: Pets are amazing!   # shown just above the title
      description: Everything about your Pets # the page body
  

• 詳細な説明を記述する。 タグの description フィールドでは {% tabs %} などの高度なブロックを含む GitBook Markdown を使用できるため、ページの導入部には通常のテキスト以上の内容を記述できます。

• Webhook をドキュメント化する： OpenAPI 3.1 では、paths と同じ形式のトップレベル webhooks フィールドを使用します。

  openapi: 3.1.0
  webhooks:
    newPet:
      post:
        summary: New pet event
        requestBody:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        responses:
          "200":
            description: Received successfully
  

Test it ランナーを設定する

インタラクティブランナーの動作は、仕様の記述内容に左右されます。ランナーは servers 配列内の URL を対象とし、components.securitySchemes で仕様に宣言されている認証のみを表示できます。Bearer／JWT、API キー、OAuth2、複数のサーバー URL やテンプレート形式のサーバー URL、操作ごとのオーバーライドなど、複雑な設定については、それぞれのパターンの YAML をコピーして使える references/test-it-setup.md を参照してください。

よくある 2 つの判断事項を紹介します。

• 「仕様を読み込めないのはなぜですか？」／「Test it が失敗するのはなぜですか？」（URL の仕様）。 ほとんどの場合、原因は CORS です。URL を指定して追加する仕様では、API がドキュメントのオリジン（たとえば https://your-site.gitbook.io やカスタムドメイン）からのクロスオリジン GET リクエストを許可する必要があります。認証情報を必要としない公開エンドポイントでは、Access-Control-Allow-Origin: * を返すことができます。
• API で CORS を有効にできない場合は？ x-enable-proxy: true を設定して、GitBook のプロキシ経由でリクエストを送信します（仕様全体に適用する場合はルートに、単一の操作に適用する場合はその操作に設定します。操作に設定した値が優先されます）。プロキシはすべての HTTP メソッド、ヘッダー、Cookie、本文を転送しますが、対象は servers に記載された URL に限られます。テストしたいすべてのベース URL がその配列に含まれていることを確認してください。詳細は references/test-it-setup.md を参照してください。

エンドポイント（または仕様全体）でランナーを非表示にするには、x-hideTryItPanel: true を設定します。

オペレーションのライフサイクルを管理する

エンドポイントがまだ本番環境で使える状態ではない場合や、段階的に廃止する場合によく使われます。特記がない限り、以下はすべてオペレーション単位です。

• まだ安定していない場合： x-stability: experimental（または alpha、beta）。
• 非推奨にする場合： deprecated: true。非推奨のエンドポイントには、公開サイトで非推奨の警告が表示されます。
• 終了日を指定して非推奨にする場合： x-deprecated-sunset: 2030-12-05 を追加します（ISO 8601、YYYY-MM-DD）。
• エンドポイント全体を非表示にする場合： x-internal: true（またはその別名 x-gitbook-ignore: true）。
• レスポンスのサンプルを1つ非表示にする場合： 該当するレスポンスオブジェクト（たとえば responses.200）に x-hideSample: true を設定します。

paths:
  /pet:
    put:
      operationId: updatePet
      x-stability: experimental
      deprecated: true
      x-deprecated-sunset: 2030-12-05

拡張機能のチートシート

GitBook がサポートする拡張機能を一覧で確認できます。各行の完全な YAML の例は、references/extensions.md を参照してください。

拡張機能	用途	設定場所
x-page-title / x-displayName	タグの表示名（ナビゲーション＋ページタイトル）	tag
x-page-description	ページタイトルの上に表示する短い説明	tag
x-page-icon	ページの Font Awesome アイコン	tag
parent / x-parent	タグを親タグの下にネストする（parent = 3.2+、x-parent = 3.0.x/3.1.x）	tag
x-hideTryItPanel	「テスト」ランナーを表示または非表示にする	root または operation
x-expandAllResponses	すべてのレスポンスセクションをデフォルトで展開する	root または operation
x-expandAllModelSections	すべてのモデル／スキーマセクションをデフォルトで展開する	root または operation
x-enable-proxy	「テスト」のリクエストを GitBook のプロキシ経由でルーティングする	root または operation（operation の設定が優先）
x-codeSamples	カスタムコードサンプル（lang、label、source）を指定する	operation
x-enumDescriptions	enum の値ごとの説明を表として表示する	schema
x-internal / x-gitbook-ignore	リファレンスからエンドポイントを非表示にする	operation
x-stability	experimental、alpha、beta のいずれかを指定する	operation
deprecated	オペレーションを非推奨としてマークする	operation
x-deprecated-sunset	非推奨のオペレーションの終了日（YYYY-MM-DD）	operation
x-hideSample	1つのレスポンスサンプルを非表示にする	response object
x-gitbook-prefix	カスタム認証プレフィックス（例：Token）。http スキームでは使用できません	security scheme
x-gitbook-token-placeholder	ランナーに表示するデフォルトのトークンプレースホルダー	security scheme

ルートのデフォルトを設定し、オペレーション側で無効にできる表示拡張機能のうち、特に重要なものが2つあります。

openapi: '3.0'
x-expandAllResponses: true        # default for every operation
x-expandAllModelSections: true
paths:
  /pets:
    get:
      x-expandAllResponses: false # opt this one out

カスタムコードサンプルを指定すると、GitBook が自動生成するスニペットが置き換えられ、複数の言語を指定できます。

paths:
  /users:
    get:
      summary: Retrieve users
      x-codeSamples:
        - lang: JavaScript
          label: Node SDK
          source: |
            import { createAPIClient } from 'my-api-sdk';
            const client = createAPIClient({ apiKey: 'my-api-key' });
            client.users.list().then(console.log);
        - lang: cURL
          label: CLI
          source: |
            curl -L -H 'Authorization: Bearer <token>' \
              'https://api.example.com/v1/users'

CI/CD で自動化する

CLI を使って、任意のパイプラインから仕様を公開できます。GITBOOK_TOKEN をシークレットとして設定し、ファイル（ビルド時に生成）または URL に対して openapi publish を実行します。URL を指定した場合、リリース後に強制的に更新されます。

export GITBOOK_TOKEN=<api-token>
gitbook openapi publish \
  --spec <spec-name> \
  --organization <organization-id> \
  example.openapi.yaml

main の仕様の変更時に実行する GitHub Actions の例：

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:
      - uses: actions/checkout@v4
      - name: Publish spec to GitBook
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <path_to_spec>