# APIリファレンスの構成

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

### 操作を複数ページに分割する

ドキュメントを整理するために、GitBook は API 操作を別々のページに分割できます。各ページは OpenAPI 仕様のタグから生成されます。操作をページにグループ化するには、各操作に同じタグを割り当てます：

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
<strong>      tags:
</strong><strong>        - pet
</strong>      summary: Update an existing pet.
      description: Update an existing pet by 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>

上記の例は次のような目次を作成します：

```
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: Everything about your Pets
```

{% endcode %}

### GitBook ブロックでリッチな説明を作成する

タグの description フィールドは GitBook マークダウンをサポートしており、以下を含みます [高度なブロック](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/creating-content/blocks) （例：タブ）:

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

```yaml
---
tags:
  - name: pet
    description: |
      Here is the detail of pets.

      {% tabs %}
      {% tab title="Dog" %}
      Here are the dogs
      {% endtab %}

      {% tab title="Cat" %}
      Here are the cats
      {% endtab %}

      {% tab title="Rabbit" %}
      Here are the rabbits
      {% endtab %}
      {% endtabs %}
```

{% endcode %}

### スキーマをハイライトする

GitBook の説明内で GitBook マークダウンを使用してスキーマをハイライトできます。以下は “petstore” 仕様から “Pet” スキーマをハイライトする例です：

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

```yaml
---
tags:
  - name: pet
      description: |
          {% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
              The Pet object
          {% endopenapi-schemas %}
```

{% endcode %}

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

GitBook は OpenAPI 3.1 を使用する場合に webhook エンドポイントのドキュメント化もサポートします。

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

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

```yaml
---
openapi: 3.1.0 # Webhooks are available starting from OpenAPI 3.1

webhooks:
  newPet:
    post:
      summary: New pet event
      description: Information about a new pet in the system
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully
```

{% endcode %}
