/openapi/ui および /api/explorer のエンドポイントで使用可能な OpenAPI ユーザー・インターフェースの外観をカスタマイズできます。 Liberty は、カスタマイズ CSS ファイルに対する変更をモニターして、 OpenAPI UI に対する変更を処理および更新します。
手順
- OpenAPI UI のヘッダー・バーにある HTML エレメントのスタイルを編集するには、CSS ファイルをカスタマイズします。
この 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) 値に設定されたロゴ・イメージを参照する必要があります。
以下のスニペットは、CSS ファイルをオーバーライドする方法を示しています。
.swagger-ui .headerbar {
background-color: #5f3345;
}
.swagger-ui .headerbar .headerbar-wrapper {
background-image: url(images/custom-logo.png);
}
- カスタマイズ CSS ファイルのモニタリングを構成します。
自動モニタリングのため、カスタム CSS ファイルを $server.config.dir/mpopenapi/customization.css と $server.config.dir/openapi-3.1/customization.css のロケーションに保存できます。 1 つ目の CSS ファイルのロケーションは、/openapi/ui エンドポイントに適用されます。 2 つ目の CSS ファイルのロケーションは、/api/explorer エンドポイントに適用されます。 カスタム・ロゴも指定したい場合は、それを $server.config.dir/mpopenapi/images/custom-logo.png と $server.config.dir/openapi-3.1/images/custom-logo.png のロケーションに保存し、両方のロケーションの CSS ファイル内で参照します。
注: 更新がモニターされるのは、CSS ファイルのみです。 ロゴ・ファイルはモニターされません。 いずれかのロゴ・ファイルに対する変更が動的に検出されるには、その変更に続けて該当 CSS ファイルへの更新が行われる必要があります。
- オプション: カスタマイズ・ファイルのファイル・モニターを制御します。
Liberty は、デフォルトで CSS カスタマイズ・ファイルを継続的にモニターします。 しかし、ファイルのモニタリングは、追加システム・リソースを使用します。 更新がないか調べるためにモニター対象ファイルをチェックする頻度を変更することができます。 カスタマイズ・ファイルがない場合は、ファイル・モニタリングをオフにした方が効果的です。
構成プロパティー
mp.openapi.extensions.liberty.file.polling.interval は、更新がないかモニター対象ファイルをチェックする頻度を指定します。 このプロパティーの値は、ゼロ以上の整数です。 間隔の単位は秒です。 デフォルト値は 2 秒です。 この値を 0 に設定すると、ファイルのモニタリングは使用不可になります。
構成は MicroProfile Config 仕様によって注入されます。
注: このプロパティーの値は、 mpOpenAPI-1.0 機能または openapi-3.1 機能が有効になっている場合にのみ検査されます。