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

# API リファレンスの構成

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

〜のどちらかを選ぶには **タグごとに1ページ** と **操作ごとに1ページ**については、 [OpenAPIレイアウト](/docs/documentation/ja-gitbook-documentation/api-references/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: 既存のペットを更新します。
      description: IDで既存のペットを更新します。
      operationId: updatePet
</code></pre>

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

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

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

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

```
Everything
├── ペット
└── ストア
```

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

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

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

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

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

{% endcode %}

### GitBook Blocksでリッチな説明を作成する

タグの説明フィールドは、GitBook Markdownをサポートしており、 [高度なブロック](/docs/documentation/ja-gitbook-documentation/creating-content/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 Markdownを使うと、GitBookの説明内でスキーマをハイライトできます。以下は、“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/api-references/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 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/api-references/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.