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

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

Everything
├── Pet
└── Store

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

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

タグセクションのカスタム拡張を使って、タイトル、アイコン、説明を追加し、ページを強化できます。すべての 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マークダウンをサポートしており、 高度なブロック などを含みます:

openapi.yaml

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

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

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

      {% tab title="Rabbit" %}
      こちらがウサギです
      {% endtab %}
      {% endtabs %}

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

GitBookマークダウンを使うと、GitBookの説明内でスキーマをハイライトできます。以下は、「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エンドポイントのドキュメント化もサポートしています。

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

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