OpenAPI レイアウト

API リファレンスの表示方法として、タグごとに1ページ、操作ごとに1ページのどちらかを選べます

OpenAPI リファレンスを挿入すると OpenAPI リファレンス、GitBook はオペレーションを 2 通りの方法で整理できます。

API の閲覧方法に合ったレイアウトを選択してください。

この設定にアクセスする

レイアウトを選択するには：

1. セクションで、 新規追加... → OpenAPI リファレンス。既存の OpenAPI リファレンスも編集できます。
2. OpenAPI スペックを選択します。
3. では ページ構成、次を選択します タグごとに 1 ページ または オペレーションごとに 1 ページ.

セットアップ全体の流れについては、次を参照してください ドキュメントに API リファレンスを挿入する.

利用可能なレイアウト

GitBook は 2 つのレイアウトをサポートしています：

• タグごとに 1 ページ 各タグごとに 1 ページを作成します。各ページには、そのタグに属するすべてのオペレーションが一覧表示されます。
• オペレーションごとに 1 ページ 各オペレーションごとに 1 ページを作成します。GitBook はそれらのページを目次内でタグごとにグループ化します。

入力例

どちらのレイアウトも、同じ OpenAPI データから始まります：

openapi.yaml

paths:
  /users:
    get:
      tags:
        - users
      summary: ユーザーを一覧表示
    post:
      tags:
        - users
      summary: ユーザーを作成

タグごとに 1 ページ

各タグが API の明確なセクションを表している場合は、このレイアウトを使用します。

概要ページを用意したい場合、ナビゲーションの項目を少なくしたい場合、関連するエンドポイントを同じページにまとめたい場合に適しています。

このレイアウトでは、両方のオペレーションが、 users タグ。

オペレーションごとに 1 ページ

個々のエンドポイントへの直接リンクが必要な場合は、このレイアウトを使用します。

大規模な API や、各エンドポイントにナビゲーション内の専用ページが必要な場合に適しています。

このレイアウトでは、GitBook は GET /users および 1 ページを POST /users。両方のページは、 users タググループ。

簡単なおすすめ

選択 タグごとに 1 ページ 小規模な API、または各タグが明確なセクションである場合に。

選択 オペレーションごとに 1 ページ 大規模な API、または各エンドポイントごとに専用ページが必要な場合に。

生成されたナビゲーションを制御する

どちらのレイアウトでも、GitBook は OpenAPI のタグを使用してリファレンスを整理します。

順序、階層、ページタイトル、アイコン、説明を制御するには、次を参照してください API リファレンスの構成.