![[17.0.0.3 and later]](../ng_v17003plus.gif)
OpenAPI 文書のカスタマイズ
/api/docs エンドポイントで使用可能なマスター OpenAPI 文書および /api/explorer の OpenAPI ユーザー・インターフェースのさまざまな局面を、externalDocs や info などのエレメントを使用してカスタマイズできます。Liberty は、デフォルト・パス・ロケーションにあるカスタマイズ・ファイルに対する変更をモニターして、マスター OpenAPI 文書および UI に対する変更を処理および更新します。
始める前に
『OpenAPI を使用した REST API 資料の生成』を参照して、OpenAPI 文書をビルドして使用可能にする方法を理解してください。
サンプル OpenAPI V3 airlines アプリケーションを使用して、文書を生成し、カスタマイズ可能な UI の例をレンダリングしてください。
手順
- OpenAPI スニペットでカスタマイズを定義します。 OpenAPI 3.0.0 仕様の構造に従ったスニペットを作成します。このスニペットは、YAML ファイルまたは JSON ファイル形式にするか、ある URL で使用可能であるようにできます。
info エレメントは、タイトル、説明、およびその他の情報を提供します。タイトルおよび説明の値をカスタマイズできます。また、ヘッダー・バーをカスタマイズして、ロゴ、フィルター・ボックス、およびフィルター・ボタンを編集することもできます。カスタマイズ・スニペットの info フィールド内で x-ibm-css フィールドを使用して、ヘッダー・バー内の HTML エレメントのスタイルを指定する CSS ファイルの場所をポイントできます。
スニペットは、それ自体で完全である必要はありません。次のスニペット例では、info エレメントをカスタマイズして、OpenAPI UI のヘッダー・バーのスタイルを指定する CSS をポイントします。
--- openapi: 3.0.0 info: title: Airlines APIs description: Book flights and manage reservations version: 2.1.0 x-ibm-css: ${server.config.dir}/openapi/header.css
CSS は、ローカル・ファイルであるか、ある URL で使用可能であることができます。パスには、ランタイム・ディレクトリーと関連付けられた Liberty 変数を組み込むことができます。
この CSS ファイルが有効と見なされるためには、以下のフォーマット要件があります。- この CSS ファイルは .swagger-ui .headerbar で始まるエレメントを少なくとも 1 つ指定します。
- .swagger-ui .headerbar で始まる CSS エレメントの下に指定されている内容のみが使用されます。
- この CSS ファイルによって参照されるカスタム・ロゴ・ファイルは PNG フォーマットである必要があります。
- カスタム・ロゴ・ファイルは custom-logo.png という名前で、images/custom-logo.png に置かれる必要があります。
- ロゴ・ファイル・パスは CSS ファイルに対する相対パスである必要があります。
- この CSS ファイルは background-image プロパティーが url(images/custom-logo.png) 値に設定されたロゴ・イメージを参照する必要があります。
.swagger-ui .headerbar { background-color: #5f3345; } .swagger-ui .headerbar .headerbar-wrapper { background-image: url(images/custom-logo.png); } .swagger-ui .headerbar .filter-wrapper .filter-button { background: rgba(252, 48, 81, 0.53); color: #e8e8e8; } .swagger-ui .headerbar .filter-wrapper input[type=text] { border: 1px solid #ebebeb; }
- カスタマイズ・ファイルのファイル・モニタリングを構成します。
カスタマイズ・ファイルを自動モニタリングのためにデフォルト・ロケーションに保存するか、または、サーバー構成を変更してファイルのロケーションを定義することができます。複数のデフォルト・カスタマイズ・ファイルが指定されている場合、モニターされるカスタマイズ・ファイルと無視されるカスタマイズ・ファイルを示す警告メッセージ出力がコンソールに表示されます。モニタリング対象として選択されたカスタマイズ・ファイルは、削除されるまでずっと Liberty によってモニターされます。
注: 更新を調べるためにモニターされるのはカスタマイズ・ファイルのみです。CSS ファイルおよびロゴ・ファイルはモニターされません。 URL はモニターされません。- デフォルトのカスタマイズ・ファイル・モニタリングを使用するため、カスタマイズ・スニペットを、YAML、YML、または JSON ファイル・タイプで ${server.config.dir}/openapi/customization.file_type に保存します。
- オプション: Liberty サーバー構成ファイルに、このスニペットを参照する customization 属性を指定した openapi エレメントを追加します。
customization 属性が明示的に設定されている場合、デフォルトのカスタマイズ定義ロケーションはモニターされません。customization 属性は、Liberty によってモニターされる、YAML ファイル、YML ファイル、または JSON ファイルを指定できます。次の例のように、パスには、ランタイム・ディレクトリーと関連付けられた Liberty 変数を組み込むことができます。
<openapi customization="${server.config.dir}/custom/customInfo.yaml" />
customization 属性は、OpenAPI スニペットを返す URL を指定することもできます。
<openapi customization="http://myWebsite.com/myCustomOpenAPI" />
- オプション: カスタマイズ・ファイルのファイル・モニタリングを使用不可にします。
Liberty は、デフォルトでは、カスタマイズ・ファイルを継続的にモニターします。しかし、ファイルのモニタリングはシステム・リソースを余分に使用します。カスタマイズ・ファイルがない場合、または、カスタマイズ・ファイルが静的であって変更されない場合は、ファイル・モニタリングをオフにした方が効果的です。
サーバー構成ファイル内で、openapi エレメントの disableFileMonitor ブール属性を true に設定します。disableFileMonitor 属性が true に設定されている場合、デフォルトのカスタマイズ定義ロケーションもモニターされません。<openapi disableFileMonitor="true" />
![[17.0.0.3 and later]](../ng_v17003plus.gif)

ファイル名: twlp_api_openapi_custom.html