OpenAPIリファレンスドキュメントを作成する

GitBookでOpenAPI/Swagger APIリファレンスドキュメントを作成、設定、構成、トラブルシュートします。GitBookのOpenAPIブロックまたは`{% openapi %}`ブロック、追加や更新が含まれるタスクで使います

GitBookはOpenAPIドキュメントを、対話可能でテスト可能なAPIリファレンスブロックに変換します。spec（JSONまたはYAML）を渡すと、エンドポイント、パラメータ、スキーマ、認証、そしてページ内リクエスト実行ツールをレンダリングします。カスタマイズのほとんどは、spec自体の中で次を通じて行います x-* 拡張であり、GitBookのUIではありません。そのため、ここでの作業の大半はOpenAPI YAMLを正しく編集することです。

このスキルは全体をカバーします。specをGitBookに取り込むこと、リファレンスページを生成すること、ナビゲーションを構成すること、「Test it」ランナーを動かすこと、操作やスキーマの表示方法を制御すること、CI/CDから更新を自動化することまで含みます。

GitBookとのやり取り方法

このスキルの大半――OpenAPI YAML/JSON自体の編集――は、転送手段に依存しません。しかし、specを へ GitBookに取り込むこと、またはリファレンスページを生成・挿入することはGitBookに触れるため、それを行う方法は1つではありません。GitBookのMCPサーバーとREST APIです。現在のセッションで実際に利用可能なものを確認し、 まずMCP：もしGitBook MCPツールがすでに接続されているなら、specの公開/更新やリファレンスページの生成など、それが扱えることは直接API呼び出しではなくそれらを使ってください。これについて検出スクリプトを実行しないでください。利用可能なツール/MCP接続はすでに把握しているはずなので、その認識をそのまま使ってください。

以下の手順は、1つの転送手段に結びつけるのではなく、成果（「specを追加する」「リファレンスページを生成する」）として説明しています。そのため、どの方法でも適用できます。GitBook MCPツールが接続されている場合は、それらを直接呼び出してください。各ツール自体のスキーマに引数が記載されています。代わりにREST API経由なら、正確なエンドポイントとリクエスト本文は下の「specificationの追加または更新」にあります。

• GitBook MCP ――同じ機能に対する完全な読み書きの面を備え、より限定された視点ではありません。まだ接続されておらず、作業が十分に大きくて導入の価値がある場合（新しいspecの公開、完全なリファレンス生成など――一度きりの微調整ではない場合）は、設定するよう提案してください： 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の別の読み取り専用「published docs」MCPサーバーとは別で、そこでは既に公開済みのコンテンツしか扱えません。
• REST API (https://api.gitbook.com/v1）— MCPが接続されていない場合、またはMCPで扱えないことを行う際の代替手段です。必要です GITBOOK_TOKEN を各リクエストのBearerヘッダーとして付ける必要があります。

同じ個人アクセストークン（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 コマンド（下の「specificationの追加または更新」を参照）は、APIやMCPと同じ基盤機能に到達します。別機能ではなく便利なラッパーであり、同じ GITBOOK_TOKEN.

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

これらはほぼすべての判断に影響するので、何かを編集する前に必ず頭に入れてください。

• サポートされるバージョン。 GitBookはSwagger 2.0とOpenAPI 3.0のspecを受け入れます。いくつかの機能には新しいバージョンが必要です。webhookにはOpenAPI 3.1が必要で、公式の parent tagプロパティにはOpenAPI 3.2+が必要です（3.0.xと3.1.xでは x-parent を使ってください）。機能のバージョン制限に触れる前に、常にspecの openapi:/swagger: のバージョンを確認してください。
• 「Test it」ランナーはScalarで動いています。 GitBookのプロキシ経由にしない限り、読者のブラウザからリクエストを実行します。
• specのソースはファイルかURLであり、更新を決めるのはそれです。どの転送手段（MCP、API、CLI、UI）で設定したかではありません。 URLソースは6時間ごとに自動更新されます。ファイルソースは再アップロードまたは再公開されたときにのみ変わります。
• x-* extensionsは名前空間化されており、共有specにそのまま残しても安全です。 あるextensionを理解しないツールはそれを無視するので、GitBook向けに組み込んだspecでも、他所で検証・動作します。

何をしたいですか？

作業を適切なセクションに対応させてください。より詳しい参考資料として、このファイルの横に2つのファイルがあります：

• 任意の x-* extensionの編集または検索。各項目の完全なYAMLは、次を読む： references/extensions.md.
• 対話型ランナーをエンドツーエンドで動かす（認証スキーム、サーバー、CORS、プロキシ）：次を読む： references/test-it-setup.md.

作業	次へ移動します:
specをGitBookに取り込む、または既存のものを更新する	「specificationの追加または更新」
リファレンスページを生成する、または単一のエンドポイント/スキーマをページに埋め込む	「APIリファレンスを挿入」
ページを分割、並べ替え、入れ子化、タイトル付け、アイコン設定する	「リファレンスの構造化」
「Test it」を動かす、CORSを修正する、認証を設定する	「Test itランナーの設定」 + references/test-it-setup.md
エンドポイントをexperimental、deprecated、またはhiddenにする	「操作ライフサイクルの管理」
拡張の正確な名前/スコープを調べる	「Extensionsチートシート」 + references/extensions.md
パイプラインからspecを自動公開する	「CI/CDで自動化」

specificationの追加または更新

ブロックやページがそれを参照する前に、specは組織内に存在していなければなりません。追加と更新は、どの転送手段でも同じ基盤操作です――上の「GitBookとのやり取り方法」で使えるものを選んでください。どれを使う場合でも、specには事前に名前/スラッグを付けてください。後で参照する方法であり、複数specを見分ける方法でもあります。

GitBook MCP ――接続されているなら、ファイルまたはURLのどちらからでもspecを作成または更新するために、そのspecツールを直接使ってください。スキーマは両方のソース型をカバーしています。

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

既存specの更新（置換）も同様に次に対して行います 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 セクションを開き、 仕様を追加をクリックし、名前を付けてから、ファイルをアップロードするかホストURLを入力するかを選びます。更新はソースに依存します。URLソースは6時間ごとに自動で確認されます（すぐに取得するには 更新を確認 をクリックしてすぐに取得し、FileからURLへ切り替えるには 編集 パンくずアクションメニューの 更新 をクリックして新しいバージョンをアップロードします。

APIリファレンスを挿入

specが存在したら、次の2つの方法のいずれかでドキュメント内に表示します。

ページ一式全体を生成する（完全なリファレンスには推奨）。 対象スペースの目次で、下部の 新規追加... をクリックし、次に OpenAPI リファレンスを選び、specを選択して挿入します。GitBookはspec内の各tagごとに1ページを作成し（「リファレンスの構造化」を参照）、必要に応じて各schemaを一覧するmodelsページも作成します。これらのページはspecが更新されるたびに更新され続けます。

既存ページに単一のoperationまたはschemaを挿入する。 押します /を検索し OpenAPIを選び、specを選び、 続行を選んでから、埋め込む特定のoperationおよび/またはschemaを選択します。

ブロック構文。 GitBookのmarkdownを直接書く場合、OpenAPI operationブロックは次のようになります（内側の行はsourceを繰り返します）：

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

1つ以上のschemaをインラインで強調表示するには（たとえばtag説明の中で）、schemasブロックを使います：

{% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
Pet オブジェクト
{% endopenapi-schemas %}

リファレンスの構造化

GitBookはspecの タグからナビゲーションを構築するので、リファレンスの構造化は主にtagの構造化です。ここで名前が挙がる各extensionの完全なYAML例は references/extensions.md.

• 操作をページに分割： 操作に同じtagを付けると、各tagが独自のページになります。

  paths:
    /pet:
      put:
        tags:
          - ペット
        summary: 既存のペットを更新します。
        operationId: updatePet

• ページを順序付け： ページの順序はトップレベルの タグ 配列内のエントリ順に従います。

  tags:
    - name: ペット
    - name: ストア
    - name: user

• ページをグループに入れ子化： 使用する parent (OpenAPI 3.2+) または x-parent (3.0.x/3.1.x) を使ってtagを親tagに向けます。

  tags:
    - name: すべて
    - name: ペット
      x-parent: すべて
    - name: ストア
      x-parent: すべて

  親ページに 説明がない場合、GitBookはサブページへリンクするカードベースのレイアウトを自動でレンダリングします。
• タグレベルのextensionを使って、ページごとにタイトル、アイコン、説明を追加します。 アイコンには任意のFont Awesome名を指定できます（https://fontawesome.com/search）。

  tags:
    - name: ペット
      x-page-title: Pet              # 目次とページヘッダーのタイトル
      x-page-icon: dog               # 目次とタイトル横のアイコン
      x-page-description: Pets are amazing!   # タイトルのすぐ上に表示
      description: Everything about your Pets # ページ本文

• 豊かな説明文を書く。 Tag 説明 fieldsはGitBook markdownを受け入れます。 {% tabs %}などの高度なブロックも含みます。そのため、ページ冒頭は単なるプレーンテキスト以上のものにできます。
• webhookを文書化する （OpenAPI 3.1）のトップレベルの webhooks フィールドで paths:

  openapi: 3.1.0
  webhooks:
    newPet:
      post:
        summary: 新しいペットのイベント
        requestBody:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        responses:
          "200":
            description: 正常に受信されました

Test itランナーを設定する

対話型ランナーは、specがそれをどう記述するか次第でしかうまく動きません。ランナーは servers 配列内のURLを対象にし、specが components.securitySchemesの下で宣言した認証しか提示できません。ベアラー/JWT、APIキー、OAuth2、複数またはテンプレート化されたサーバーURL、operationごとの上書きなど、非自明なものについては、各パターンのコピペ用YAMLが載っている references/test-it-setup.mdを読んでください。

常にぶつかる2つの素早い判断があります：

• 「なぜspecが読み込まれないのか？」 / 「なぜTest itが失敗するのか？」（URL spec）。 これはほぼ常にCORSです。URL追加のspecでは、APIがドキュメントのオリジンからのクロスオリジンGETリクエストを許可する必要があります（例： https://your-site.gitbook.io またはカスタムドメイン）。公開され、認証不要のエンドポイントは Access-Control-Allow-Origin: *.
• APIでCORSを有効化できない？ GitBookのプロキシを介してリクエストを送るには x-enable-proxy: true を使います（spec全体のルートで、または単一operation上で；operation側の値が優先されます）。プロキシはすべてのHTTPメソッド、ヘッダー、cookie、bodyを転送しますが、 serversに列挙されたURLに対してのみです。したがって、テストしたいすべてのベースURLがその配列に入っていることを確認してください。詳細は references/test-it-setup.md.

ランナーをエンドポイント（またはspec全体）から削除するには、 x-hideTryItPanel: true.

操作ライフサイクルの管理

エンドポイントが本番対応前、または段階的に廃止されているときによく使います。以下は、特記ない限りすべてoperationレベルです。

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

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

Extensionsチートシート

GitBookでサポートされるすべてのextensionをひと目で確認。任意の行の完全なYAML例を見るには references/extensions.md.

Extension	目的	配置場所
x-page-title / x-displayName	tagの表示名（ナビゲーション + ページタイトル）	タグを使用したクイックセットアップ
x-page-description	ページタイトルの上に表示される短い説明	タグを使用したクイックセットアップ
x-page-icon	ページ用のFont Awesomeアイコン	タグを使用したクイックセットアップ
parent / x-parent	tagを親tagの下に入れ子化する（parent = 3.2+, x-parent = 3.0.x/3.1.x）	タグを使用したクイックセットアップ
x-hideTryItPanel	「Test it」ランナーを表示または非表示にする	ルートまたはoperation
x-expandAllResponses	すべてのresponseセクションをデフォルトで展開する	ルートまたはoperation
x-expandAllModelSections	すべてのmodel/schemaセクションをデフォルトで展開する	ルートまたはoperation
x-enable-proxy	「Test it」リクエストをGitBookのプロキシ経由にする	ルートまたはoperation（operationが優先）
x-codeSamples	カスタムコードサンプルを提供する（lang, label, source)	operation
x-enumDescriptions	あるスキーマの各値についての説明 enumを表としてレンダリングする	スキーマ
x-internal / x-gitbook-ignore	リファレンスからエンドポイントを非表示にする	operation
x-stability	マーク experimental, alphaのような一般的なクレームや、 beta	operation
deprecated	operationを非推奨としてマークする	operation
x-deprecated-sunset	非推奨operationのサンセット日（YYYY-MM-DD)	operation
x-hideSample	単一のresponseサンプルを非表示にする	responseオブジェクト
x-gitbook-prefix	カスタム認証プレフィックス（例： Token）；では使用不可 http スキーム	security scheme
x-gitbook-token-placeholder	ランナーに表示されるデフォルトのトークンプレースホルダー	security scheme

ここで強調しておく価値がある表示用extensionが2つあります。ルート側のデフォルトを持ち、operationがそれをオプトアウトできます：

openapi: '3.0'
x-expandAllResponses: true        # すべてのoperationのデフォルト
x-expandAllModelSections: true
paths:
  /pets:
    get:
      x-expandAllResponses: false # これだけオプトアウト

カスタムコードサンプルはGitBookの自動生成スニペットを置き換え、複数言語を受け付けます：

paths:
  /users:
    get:
      summary: ユーザーを取得
      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を使って任意のパイプラインからspecを公開します。 GITBOOK_TOKEN をシークレットとして設定し、次を実行します openapi publish ビルド中に生成されたファイルに対して、またはURLに対して実行します（リリース後に更新を強制します）。

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

GitHub Actionsの例。specの変更をトリガーとして main:

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:
      - 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>