API リファレンスの構成

アイコンと説明を使って、複数ページにまたがる API リファレンスを構成する方法を学びます

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

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

ドキュメントを整理された状態に保つため、GitBook は API の操作を別々のページに分割できます。各ページは OpenAPI スペック内のタグから生成されます。操作を 1 つのページにまとめるには、各操作に同じタグを割り当てます。

openapi.yaml

paths:
  /pet:
    put:
      tags:
        - pet
      summary: 既存のペットを更新します。
      description: ID によって既存のペットを更新します。
      operationId: updatePet

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

GitBook におけるページの順序は、OpenAPI の tags 配列内のタグの順序と一致します。

openapi.yaml

tags:
  - name: pet
  - name: store
  - name: user

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

複数レベルのナビゲーションを構築するには、タグ内で x-parent （または parent）を使用して階層を定義します。

openapi.yaml

tags:
  - name: everything
  - name: pet
    x-parent: everything
  - name: store
    x-parent: everything

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

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

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

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

tags セクションのカスタム拡張を使って、タイトル、アイコン、説明でページを強化できます。すべての Font Awesome アイコン は x-page-icon.

openapi.yaml

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

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

タグの説明フィールドは GitBook の Markdown をサポートしており、 高度なブロック のようなタブも含まれます。

openapi.yaml

---
tags:
  - name: pet
    description: |
      こちらはペットの詳細です。

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

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

      {% tab title="Rabbit" %}
      こちらはうさぎです
      {% endtab %}
      {% endtabs %}

スキーマを強調表示する

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

openapi.yaml

---
tags:
  - name: pet
      description: |
          {% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
              Pet オブジェクト
          {% endopenapi-schemas %}

Webhook エンドポイントをドキュメント化する

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

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

openapi.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 ステータスを返します