> 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/kontentsuwosuru/openapi/guides/structuring-your-api-reference.md).

# APIリファレンスの構成

GitBook は OpenAPI 仕様をレンダリングするだけではありません。より分かりやすく、ナビゲーションしやすく、ブランドに合った API リファレンスにカスタマイズできます。

選択するには **タグごとに1ページ** 、 **操作ごとに1ページ**、詳しくは [OpenAPI レイアウト](/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi/guides/openapi-layouts.md).

このページでは、タグを使って生成されたナビゲーションを制御する方法を説明します。

### タグを使って生成ページを整理する

GitBook は、両方のレイアウトでタグを使って生成された API リファレンスページを整理します。

〜を使用すると **タグごとに1ページ**、GitBook はタグごとに 1 ページを作成します。〜を使用すると **操作ごとに1ページ**、GitBook は操作ごとに 1 ページを作成し、タグを使ってそれらのページを目次内でグループ化します。

関連する操作をグループ化するには、各操作に同じタグを割り当てます:

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
<strong>      tags:
</strong><strong>        - pet
</strong>      summary: 既存の pet を更新します。
      description: ID によって既存の pet を更新します。
      operationId: updatePet
</code></pre>

### 目次内でページの順序を並べ替える

生成されるタグページまたはタググループの順序は、OpenAPI 内のタグの順序と一致します `タグ` 配列:

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags:
<strong>  - name: pet
</strong><strong>  - name: store
</strong><strong>  - name: user
</strong></code></pre>

### ページをグループにネストする

多階層のナビゲーションを構築するには、 `x-parent` （または `parent`）をタグ内で使用して階層を定義します。これはどちらのページ構成でも機能します:

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags:
  - name: everything
  - name: pet
<strong>    x-parent: everything
</strong>  - name: store
<strong>    x-parent: everything
</strong></code></pre>

上記の例では、次のような目次が作成されます:

```
すべて
├── Pet
└── Store
```

GitBook が親ページを生成し、そのページに説明がない場合、子ページにカードベースのレイアウトを表示します。

### ページタイトル、アイコン、説明をカスタマイズする

生成されたタグページとナビゲーションラベルを、 `タグ` セクション内のカスタム拡張で強化できます。すべての [Font Awesome アイコン](https://fontawesome.com/search) は `x-page-icon`.

{% code title="openapi.yaml" %}

```yaml
tags:
  - name: pet
    # 目次とページに表示されるページタイトル
    x-page-title: Pet
    # 目次とページタイトルの横に表示されるアイコン
    x-page-icon: dog
    # タイトルのすぐ上に表示される説明
    x-page-description: ペットは素晴らしいです！
    # ページの内容
    description: あなたのペットに関するすべて
```

{% endcode %}

### GitBook Blocks で豊かな説明を作成する

タグの description フィールドは、GitBook Markdown をサポートしており、 [高度なブロック](/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/blocks.md) たとえばタブ:

{% code title="openapi.yaml" %}

```yaml
---
tags:
  - name: pet
    description: |
      こちらにペットの詳細があります。

      {% tabs %}
      {% tab title="Dog" %}
      こちらが犬です
      {% endtab %}

      {% tab title="Cat" %}
      こちらが猫です
      {% endtab %}

      {% tab title="Rabbit" %}
      こちらがウサギです
      {% endtab %}
      {% endtabs %}
```

{% endcode %}

### スキーマを強調表示する

GitBook の説明内で GitBook Markdown を使ってスキーマを強調表示できます。次は、“petstore” 仕様の “Pet” スキーマを強調表示する例です:

{% code title="openapi.yaml" %}

```yaml
---
tags:
  - name: pet
      description: |
          {% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
              Pet オブジェクト
          {% endopenapi-schemas %}
```

{% endcode %}

### Webhook エンドポイントを文書化する

GitBook は webhook エンドポイントを含む OpenAPI 3.1 をサポートしています。

その `webhooks` フィールドは OpenAPI 3.1 の一部であるため、仕様で OpenAPI 3.1 バージョンを宣言する必要があります。webhook は OpenAPI ファイル内で直接定義でき、GitBook は他の API 操作と並べてそれらをレンダリングします。OpenAPI ドキュメント全体のバージョンサポートについては、 [OpenAPI の互換性](/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi.md#openapi-compatibility).

{% code title="openapi.yaml" %}

```yaml
---
openapi: 3.1.0 # Webhooks は OpenAPI 3.1 から利用できます

webhooks:
  newPet:
    post:
      summary: 新しい pet のイベント
      description: システム内の新しい pet に関する情報
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: データが正常に受信されたことを示すために 200 ステータスを返します
```

{% endcode %}


---

# 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/kontentsuwosuru/openapi/guides/structuring-your-api-reference.md?ask=<question>&goal=<endgoal>
```

`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.