# API リファレンスの構成

GitBook は、OpenAPI 仕様をただレンダリングするだけではありません。API リファレンスをカスタマイズして、わかりやすさ、ナビゲーション、ブランディングを向上させることができます。

### オペレーションを複数ページに分割する

ドキュメントを整理して保つために、GitBook では API オペレーションを個別のページに分割できます。各ページは OpenAPI 仕様のタグから生成されます。オペレーションを 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>

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

GitBook でのページの順序は、OpenAPI の tags 配列内のタグの順序と一致します:

<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
├── 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: Pets are amazing!
    # ページの内容
    description: ペットに関するすべて
```

{% endcode %}

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

タグの説明フィールドでは、GitBook のマークダウンがサポートされており、 [高度なブロック](/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 の説明内で 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 は、OpenAPI 3.1 を使用する場合に Webhook エンドポイントのドキュメント化もサポートしています。

以下の `webhooks` フィールドを使って、OpenAPI ファイル内で直接 webhook を定義できます。これは次のものと同様に機能します。 `paths` 通常の API エンドポイント用の:

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

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

The question should be specific, self-contained, and written in natural language.
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.