> 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 リファレンスの構成

アイコンや説明を使って、複数ページにわたる 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>        - ペット
</strong>      summary: 既存のペットを更新します。
      description: ID で既存のペットを更新します。
      operationId: updatePet
</code></pre>

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

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

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags:
<strong>  - name: ペット
</strong><strong>  - name: ストア
</strong><strong>  - name: user
</strong></code></pre>

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

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

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags:
  - name: すべて
  - name: ペット
<strong>    x-parent: すべて
</strong>  - name: ストア
<strong>    x-parent: すべて
</strong></code></pre>

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

```
すべて
├── ペット
└── ストア
```

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

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

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

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

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

{% endcode %}

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

タグの description フィールドは、GitBook マークダウンに対応しており、 [高度なブロック](/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/blocks.md) たとえばタブ：

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

```yaml
---
tags:
  - name: ペット
    description: |
      ペットの詳細は次のとおりです。

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

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

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

{% endcode %}

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

GitBook の説明内では、GitBook マークダウンを使ってスキーマを強調表示できます。以下は、「petstore」仕様の「Pet」スキーマを強調表示する例です：

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

```yaml
---
tags:
  - name: ペット
      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 のバージョンを宣言する必要があります。OpenAPI ファイルに webhook を直接定義でき、GitBook はそれらを他の API オペレーションと並べてレンダリングします。OpenAPI ドキュメントのバージョンサポートについては、 [OpenAPI 互換性](/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi.md#openapi-compatibility).

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

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

webhooks:
  newPet:
    post:
      summary: 新しいペットのイベント
      description: システム内の新しいペットに関する情報
      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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/openapi/guides/structuring-your-api-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.