API リファレンスの構成

アイコンや説明を使って、複数ページにわたる API リファレンスの構成方法を学ぶ

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

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

ドキュメントを整理して保つために、GitBook では API オペレーションを個別のページに分割できます。各ページは OpenAPI 仕様のタグから生成されます。オペレーションを 1 つのページにまとめるには、各オペレーションに同じタグを割り当てます:

openapi.yaml

paths:
  /pet:
    put:
      tags:
        - pet
      summary: 既存の pet を更新します。
      description: Id によって既存の pet を更新します。
      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: Pets are amazing!
    # ページの内容
    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 エンドポイントのドキュメント化もサポートしています。

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

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