API リファレンスの構造化

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

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

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

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

openapi.yaml

paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet.
      description: Update an existing pet by 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: Pets are amazing!
    # ページの内容
    description: Everything about your Pets

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

タグの description フィールドは GitBook マークダウンをサポートしており、以下を含みます 高度なブロック （例：タブ）:

openapi.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 %}

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

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

openapi.yaml

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

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

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

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

openapi.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