# 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: 既存のペットを更新します。
      description: ID によって既存のペットを更新します。
      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>

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

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

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

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

tags セクションのカスタム拡張を使って、タイトル、アイコン、説明でページを強化できます。すべての [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 でリッチな説明を作成する

タグの説明フィールドは GitBook の Markdown をサポートしており、 [高度なブロック](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/ja-gitbook-documentation/creating-content/blocks) のようなタブも含まれます。

{% 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 は OpenAPI 3.1 を使用する場合、Webhook エンドポイントのドキュメント化もサポートしています。

Webhook は OpenAPI ファイル内で直接定義できます。 `webhooks` フィールドを使用し、これは `paths` が通常の API エンドポイントに対して行うのと同様に機能します。

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

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

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

{% endcode %}