> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/skill/write-openapi.md). # OpenAPIリファレンスドキュメントを作成する GitBookでOpenAPI/SwaggerのAPIリファレンスドキュメントを作成、設定、構成、トラブルシューティングする。GitBookのOpenAPIブロックまたは \`{% openapi %}\` ブロックに関わる作業、追加または更新に関係する場合は、これを使用する GitBook は OpenAPI ドキュメントを、インタラクティブでテスト可能な API リファレンスブロックに変換します。仕様（JSON または YAML）を渡すと、エンドポイント、パラメータ、スキーマ、認証、ページ内リクエスト実行ツールをレンダリングします。カスタマイズの大半は、仕様そのものの中で `x-*` 拡張によって行われ、GitBook の UI では行いません。そのため、ここでの作業の大半は OpenAPI YAML を正しく編集することです。 このスキルでは、仕様を GitBook に取り込むこと、リファレンスページを生成すること、ナビゲーションを構成すること、「Test it」実行ツールを動かすこと、操作やスキーマの表示方法を制御すること、CI/CD から更新を自動化することまで、全体を扱います。 ## GitBook と対話する方法 このスキルの大部分――OpenAPI YAML/JSON そのものを編集すること――は、転送手段に依存しません。ですが、仕様を *GitBook に* 取り込むこと、あるいはリファレンスページを生成・挿入することは GitBook に触れます。方法は複数あり、GitBook の MCP サーバーと REST API があります。現在のセッションで実際に利用できるものを確認し、 **まず MCP**: もし GitBook の MCP ツールがすでに接続されているなら、それらが対応する処理（仕様の公開/更新、リファレンスページの生成）には直接 API を呼ぶのではなくそれらを使ってください。これを判定するスクリプトは実行しないでください。自分の利用可能なツール/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 でカバーされていないものを扱うための代替手段です。必要なのは `GITBOOK_TOKEN` を bearer ヘッダーとして毎回のリクエストに付けることです。 同じ個人アクセストークン（ で取得）を、どちらにも bearer トークンとして使えます。MCP ではさらに、トークンを貼り付けるよりも簡単な代替として OAuth もサポートしています。 **トークンが必要になった場合** (REST API 経路、または OAuth なしの MCP）では、セッションの最初に確認してください： ```bash [ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set" ``` もし `GITBOOK_TOKEN` が設定されていない場合は、ユーザーに直接次を尋ねてください： 1. GitBook の個人アクセストークンが必要だと伝えてください。 **** で作成するよう案内してください。 2. トークンを会話に貼り付けてもらうよう依頼してください。すぐに環境変数として export し（`export GITBOOK_TOKEN=<貼り付けた値>`）、応答でその値を繰り返さないでください。 3. トークンが環境に存在することが確認されるまで、いかなる API 呼び出しも行わないでください。 トークンをファイルに書き込まない、応答で絶対にそのまま返さない、コミットしないでください。 GitBook CLI の `gitbook openapi publish` コマンド（下の「仕様を追加または更新する」を参照）は、API や MCP と同じ基盤機能に到達します――これは便利なラッパーであって、別機能セットではありません。認証には同じ `GITBOOK_TOKEN`. ## まず知っておくべき重要事項 これらはほぼすべての判断に影響するため、何かを編集する前に頭に入れておいてください。 * **対応バージョン。** GitBook は Swagger 2.0 と OpenAPI 3.0 の仕様を受け付けます。いくつかの機能には新しいバージョンが必要です。webhook には OpenAPI 3.1 が必要で、公式の `親` タグプロパティには OpenAPI 3.2 以上が必要です（ `x-parent` を 3.0.x と 3.1.x で使ってください）。版指定のある機能に手を出す前に、必ず仕様の `openapi:`/`swagger:` バージョンを確認してください。 * **「Test it」実行ツールは Scalar によって動作します。** 仕様で指示された URL を、GitBook のプロキシ経由にしない限り、読者のブラウザから実行します。 * **仕様のソースはファイルまたは URL です――そして更新を決めるのはそれであり、どの転送手段（MCP、API、CLI、UI）を使って設定したかではありません。** URL ソースは 6 時間ごとに自動更新されます。ファイルソースは再アップロードまたは再公開したときだけ変更されます。 * **`x-*` 拡張は名前空間化されており、共有仕様に置いても安全です。** 指定した拡張を理解しないツールはそれを無視するので、GitBook 用に拡張を加えた仕様でも、他の場所で検証され動作します。 ## 何をしたいですか？ 作業内容に合ったセクションを選んでください。より詳しいリファレンス資料として、このファイルの横に 2 つのファイルがあります： * 任意の `x-*` 拡張を編集または調べる場合。各 YAML 例はすべて含まれます。読むのは `references/extensions.md`. * インタラクティブな実行ツールをエンドツーエンドで動かす（認証方式、サーバー、CORS、プロキシ）：読むのは `references/test-it-setup.md`. | 作業 | 移動先 | | ----------------------------------------------- | ---------------------------------------------------- | | 仕様を GitBook に取り込む、または更新する | 「仕様を追加または更新する」 | | リファレンスページを生成する、または 1 つのエンドポイント/スキーマをページに挿入する | 「API リファレンスを挿入する」 | | ページを分割、順序付け、ネスト、タイトル付け、アイコン設定する | 「リファレンスを構成する」 | | 「Test it」を動かす、CORS を修正する、認証を設定する | 「Test it 実行ツールを設定する」 + `references/test-it-setup.md` | | エンドポイントを experimental、deprecated、または hidden にする | 「操作のライフサイクルを管理する」 | | 拡張の正確な名前/スコープを調べる | 「拡張チートシート」 + `references/extensions.md` | | パイプラインから仕様を自動公開する | 「CI/CD で自動化する」 | ## 仕様を追加または更新する ブロックやページから参照できるようになる前に、仕様は組織内に存在していなければなりません。追加と更新は、どの転送手段でも同じ基盤操作です――上の「GitBook と対話する方法」で使えるものを選んでください。どれを使う場合でも、仕様にはあらかじめ名前/スラッグを付けてください。後で参照するとき、また複数の仕様を見分けるときにそれを使います。 **GitBook MCP** ――接続されているなら、仕様の作成または更新に、その仕様ツールをファイルまたは URL のどちらからでも直接使ってください。スキーマは両方のソース型をカバーしています。 **REST API** ――URL ソースから作成： ```bash curl -s -X POST -H "Authorization: Bearer $GITBOOK_TOKEN" \ -H "Content-Type: application/json" \ -d '{"slug": "", "source": {"url": ""}}' \ https://api.gitbook.com/v1/orgs/$ORG_ID/openapi ``` またはファイルから： ```bash curl -s -X POST -H "Authorization: Bearer $GITBOOK_TOKEN" \ -F "slug=" \ -F "file=@./openapi.yaml" \ https://api.gitbook.com/v1/orgs/$ORG_ID/openapi ``` 既存の仕様を更新（置換）する場合も、同じ方法で次に対して行います `PATCH /v1/orgs/{orgId}/openapi/{specId}`. **GitBook CLI** ――API 呼び出しと同じ機能をそのまま薄くラップしたものです。スクリプトやパイプラインで便利です（同じコマンドで追加・更新の両方ができ、URL に対して実行すると更新も強制します）： ```bash gitbook openapi publish --spec --organization ``` パイプライン自動化については「CI/CD で自動化する」を参照してください。CLI の詳細： **GitBook アプリ UI** ――左側バーの **OpenAPI** セクションを開き、 **仕様を追加**をクリックし、名前を付けてから、ファイルをアップロードするかホスト済み URL を入力するかを選びます。更新はソースに依存します。URL ソースは 6 時間ごとに自動チェックされます（すぐに取得するには **更新を確認** をクリックしてください。パンくずのアクションメニューの **編集** から File を URL に切り替えます）。ファイルソースは新しいバージョンをアップロードするために **更新** が必要です。 ## API リファレンスを挿入する 仕様が存在すれば、ドキュメント内に次の 2 つの方法のいずれかで表示できます。 **ページを丸ごと生成する（完全なリファレンスには推奨）。** 対象スペースの目次で、下部の **新規追加...** をクリックし、 **OpenAPI Reference**を選び、仕様を選択して挿入します。GitBook は仕様内のタグごとに 1 ページを作成し（「リファレンスを構成する」を参照）、必要に応じてすべてのスキーマを一覧する models ページも作成します。これらのページは仕様が更新されるたびに自動で更新され続けます。 **既存のページに、単一の操作またはスキーマを挿入します。** を押し、 `/`を検索し、 **OpenAPI**を選び、 **続行**を選択して、埋め込む特定の操作やスキーマを選びます。 **ブロック構文。** 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" %} Pet オブジェクト {% endopenapi-schemas %} ``` ## リファレンスを構成する GitBook は仕様の `tags`からナビゲーションを構築するため、リファレンス構成は主にタグの構成です。ここに挙げた各拡張の完全な YAML は `references/extensions.md`. * **ページを分割する：** 操作に同じ tag を付けると、各 tag がそれぞれ独自のページになります。 ```yaml paths: /pet: put: tags: - pet summary: 既存の pet を更新します。 operationId: updatePet ``` * **ページを順序付ける：** ページ順は最上位 `tags` 配列のエントリ順に従います。 ```yaml tags: - name: pet - name: store - name: user ``` * **ページをグループにネストする：** 使います `親` （OpenAPI 3.2+）または `x-parent` （3.0.x/3.1.x）で tag を親タグに向けます。 ```yaml tags: - name: everything - name: pet x-parent: everything - name: store x-parent: everything ``` 親ページに `description`がなければ、GitBook は自動的に子ページへのリンクを持つカードベースのレイアウトをレンダリングします。 * **ページごとにタイトル、アイコン、説明を追加する** には tag レベルの拡張を使います。アイコンには任意の Font Awesome 名を使えます（ ```yaml tags: - name: pet x-page-title: Pet # 目次とページヘッダーのタイトル x-page-icon: dog # ToC とタイトル横のアイコン x-page-description: Pets are amazing! # タイトルのすぐ上に表示 description: ペットについてのすべて # ページ本文 ``` * **豊かな説明を書く。** Tag `description` fields は GitBook markdown を受け付けます。 `{% tabs %}`そのためページの導入文は単なるテキスト以上のものにできます。 * **webhook を文書化する** (OpenAPI 3.1) のトップレベル `webhooks` フィールドで、 `paths`: ```yaml openapi: 3.1.0 webhooks: newPet: post: summary: 新しい pet イベント requestBody: content: application/json: schema: $ref: "#/components/schemas/Pet" responses: "200": description: 正常に受信しました ``` ## Test it 実行ツールを設定する インタラクティブな実行ツールは、仕様がどれだけ正確に記述しているかに応じてしか機能しません。実行ツールは `servers` 配列内の URL を対象にし、仕様が `components.securitySchemes`の下で宣言している認証しか提示できません。Bearer/JWT、API キー、OAuth2、複数またはテンプレート化されたサーバー URL、操作ごとの上書きなど、非自明なものについては `references/test-it-setup.md`を読み、各パターンのコピペ用 YAML を参照してください。 あなたが頻繁に直面する 2 つの素早い判断： * **「なぜ私の仕様は読み込まれないの？」 / 「なぜ Test it が失敗するの？」（URL 仕様）。** 原因はほぼ常に CORS です。URL で追加された仕様では、API が docs の origin からのクロスオリジン GET リクエストを許可している必要があります（例： `https://your-site.gitbook.io` や独自ドメイン）。公開されていて認証不要なエンドポイントは `Access-Control-Allow-Origin: *`. * **を返せます。** API で CORS を有効にできませんか？ `GitBook のプロキシ経由でリクエストをルーティングします。` x-enable-proxy: true `servers`（仕様全体のルートに置くか、単一の操作に置きます。操作側の値が優先されます）。プロキシはすべての HTTP メソッド、ヘッダー、Cookie、ボディを転送しますが、 `references/test-it-setup.md`. に列挙された URL にしか送れません。したがって、テストしたいベース URL はすべてその配列に入れてください。詳細は `エンドポイント（または仕様全体）から実行ツールを削除するには、`. ## 操作のライフサイクルを管理する エンドポイントが本番対応でない場合や段階的に廃止されている場合によく使います。以下は、注記があるものを除きすべて operation-level です。 * **まだ安定していない：** `x-stability: experimental` (または `アルファ` または `ベータ`). * **廃止予定：** `deprecated: true`。廃止予定のエンドポイントは公開サイトで非推奨警告が表示されます。 * **終了日付きで廃止予定：** 追加する `x-deprecated-sunset: 2030-12-05` (ISO 8601、 `YYYY-MM-DD`). * **エンドポイント全体を隠す：** `x-internal: true` （またはその別名 `x-gitbook-ignore: true`). * **1 つのレスポンスサンプルを隠す：** 設定する `x-hideSample: true` をそのレスポンスオブジェクトに設定します（たとえば `responses.200`). ```yaml 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 の表示名（ナビゲーション + ページタイトル） | tag | | `x-page-description` | ページタイトルの上に表示される短い説明 | tag | | `x-page-icon` | ページ用の Font Awesome アイコン | tag | | `親` / `x-parent` | 親 tag の下に tag をネストする（`親` = 3.2+, `x-parent` = 3.0.x/3.1.x） | tag | | `x-hideTryItPanel` | "Test it" 実行ツールを表示/非表示にする | root または operation | | `x-expandAllResponses` | すべてのレスポンスセクションをデフォルトで展開する | root または operation | | `x-expandAllModelSections` | すべてのモデル/スキーマセクションをデフォルトで展開する | root または operation | | `x-enable-proxy` | "Test it" リクエストを GitBook のプロキシ経由にする | root または operation（operation が優先） | | `x-codeSamples` | カスタムコードサンプルを提供する（`lang`, `label`, `source`) | operation | | `x-enumDescriptions` | 各値ごとの `enum`の説明。表として表示される | schema | | `x-internal` / `x-gitbook-ignore` | リファレンスからエンドポイントを隠す | operation | | `x-stability` | マークする `experimental`, `アルファ`、また `ベータ` | operation | | `deprecated` | operation を廃止予定にする | operation | | `x-deprecated-sunset` | 廃止予定 operation の終了日（`YYYY-MM-DD`) | operation | | `x-hideSample` | 単一のレスポンスサンプルを隠す | response object | | `x-gitbook-prefix` | カスタム認証プレフィックス（例： `トークン`）； `http` スキーム | security scheme | | `x-gitbook-token-placeholder` | 実行ツールに表示されるデフォルトのトークンプレースホルダー | security scheme | ここで強調すべき 2 つの表示拡張があります。これは、操作側でオプトアウトできるルートのデフォルトを持つためです： ```yaml openapi: '3.0' x-expandAllResponses: true # すべての操作のデフォルト x-expandAllModelSections: true paths: /pets: get: x-expandAllResponses: false # これだけオプトアウトする ``` カスタムコードサンプルは GitBook の自動生成スニペットを置き換え、複数の言語を受け付けます： ```yaml 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 ' \ 'https://api.example.com/v1/users' ``` ## CI/CD で自動化 CLI を使って、任意のパイプラインから仕様を公開します。次を設定し `GITBOOK_TOKEN` をシークレットとして設定し、その後次を実行します `openapi publish` ファイル（ビルド中に生成されたもの）または URL（リリース後に更新を強制します）に対して実行します。 ```bash export GITBOOK_TOKEN= gitbook openapi publish \ --spec \ --organization \ example.openapi.yaml ``` 仕様変更時にトリガーされる GitHub Actions の例、対象は `main`: ```yaml 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: 仕様を GitBook に公開 run: | npx -y @gitbook/cli@latest openapi publish \ --spec "$GITBOOK_SPEC_NAME" \ --organization "$GITBOOK_ORGANIZATION_ID" \ ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/skill/write-openapi.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.