OpenAPI / Swagger
OpenAPI / Swagger
OpenAPI/Swagger 仕様に対するインタラクティブな
Swagger UI ウィジェットです。
コンテンツブロック のどのブロックとも同じ
::: name ... ::: コンテナ構文を使い、GitBook 自身の OpenAPI ブロックの
直接の対応物です。src は ::: file の src（コンテンツブロック
参照）と同じく、docs/assets/ からの相対パスとして解決されます。
JSON・YAML どちらの仕様ファイルにも対応しており、Swagger UI が
クライアント側で完全にパースします - このモジュールのどこにもサーバー側
での OpenAPI パースは存在しません。bxsites.yaml の
openapi を true に設定する必要があります
- 設定されていない場合、このプレースホルダーはレンダリングされますが動作
しません（Swagger UI 自体の JS/CSS が
site/に一切コピーされないため、 この機能を使わない他のすべてのプロジェクトのビルドサイズはこれまでどおり 小さいままです）:
::: openapi src="assets/openapi/example.yaml" title="Bookshelf API"
:::
上のウィジェットはまさにこのページ自身がライブでレンダリングしているもの
で、このガイドが同梱する小さなサンプル仕様
docs/assets/openapi/example.yaml を表示しています - 自分のプロジェクトの
docs/assets/ 配下に置いて開く（あるいは src を既存の自分の仕様ファイル
に向ける）ことで、自分の API についても同じように表示できます。
同梱(ベンダリング)しているのは SwaggerUIBundle 自体のベースレイアウトの
みです - 別の仕様を入力できるトップバー/「Explore」バーは含まれません
（::: openapi ブロックは、著者が指定した唯一の仕様を常に表示するように
意図されているためです）。そのため、各オペレーションとそのリクエスト/
レスポンススキーマ、そして「Try it out」（訪問者のブラウザから仕様自身の
servers[0].url へ直接呼び出します - そのサーバーがドキュメントのホスト元
からの CORS を許可していることを確認してください）は、何も書き換えること
なく既存の仕様からそのままレンダリングされます。
エンドポイント1件をインライン表示
operation="METHOD /path" を追加すると、そのエンドポイント1件だけを通常の
ページ内にそのまま配置できます - チュートリアルの途中で、読者を完全な
リファレンスへ送り出すことなく使えて便利です:
::: openapi src="assets/openapi/example.yaml" operation="GET /books"
:::
上のフルブロックとまったく同じ Swagger UI ウィジェットです（同じ仕様、
同じくクライアント側のみのレンダリング - operation もこちら側で
OpenAPI パースを一切トリガーしません）。Swagger UI 自身がすでにレンダリング
済みのマークアップを読み取ることで、他のすべてのオペレーションは単に
非表示にされ、このオペレーションだけが自動的に展開されます。operation
のメソッドは大文字小文字を区別しませんが、パスは仕様自身のパス
（{param} プレースホルダーも含めて）と完全に一致する必要があります。
仕様ファイルなしで API をドキュメント化する
::: openapi には常に src に実在する OpenAPI/Swagger ドキュメントが
必要です - 1件のエンドポイントを手書きで説明するための、仕様ファイル不要
の手動版ブロックは存在しません。GitBook 自身も同様で、かつて存在した
対応物「API method」ブロックは 2024年2月に廃止され、常に実際の仕様を
インポートする方式に一本化されました。まだ仕様がない場合は:
- 今いるページに必要な分だけ仕様を書きます。最小限の
info/serversを伴うpathsの1エントリだけでも（docs/assets/openapi/example.yamlを見ると、実際にどれだけ少なくて済むかがわかります）、そのエンドポイント 1件分のインタラクティブなウィジェットと「Try it out」が手に入ります - 後から完全な仕様へ育てていけばよく、ブロック自体は何も変わりません。 - あるいはウィジェットを使わず、通常のコンテンツとしてエンドポイントを 説明します - パラメータの表や、リクエスト/レスポンスの
[ステッパー](content-blocks.md#ステッパー) で手順化します。`openapi`
が有効かどうかに関わらず、他のすべてのコンテンツブロックと Markdown
拡張機能はどのページでも使えます。