[18.0.0.1 and later]

OpenAPI ユーザー・インターフェースのカスタマイズ

/openapi/ui エンドポイントで使用可能な OpenAPI ユーザー・インターフェースの外観をカスタマイズできます。Liberty は、カスタマイズ CSS ファイルへの変更をモニターして、OpenAPI UI への変更を処理および更新します。

始める前に

MicroProfile OpenAPI 1.0 を使用した REST API 資料の生成』を参照して、OpenAPI 文書をビルドして使用可能にする方法を理解してください。

手順

  1. 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);
    }
  2. カスタマイズ CSS ファイルのモニタリングを構成します。

    自動モニタリングのため、カスタム CSS ファイルを $server.config.dir/mpopenapi/customization.css ロケーションに保存できます。カスタム・ロゴも指定したい場合は、それを $server.config.dir/mpopenapi/images/custom-logo.png ロケーションに保存し、CSS ファイル内で参照します。

    注: 更新がないか調べるためにモニターされるのは CSS ファイルのみです。ロゴ・ファイルはモニターされません。ロゴ・ファイルに対する変更が動的に検出されるには、その変更に続けて CSS ファイルへの更新が行われる必要があります。
  3. オプション: カスタマイズ・ファイルのファイル・モニタリングを制御します。

    Liberty は、デフォルトでは、CSS カスタマイズ・ファイルを継続的にモニターします。しかし、ファイルのモニタリングは、追加システム・リソースを使用します。更新がないか調べるためにモニター対象ファイルをチェックする頻度を変更することができます。カスタマイズ・ファイルがない場合は、ファイル・モニタリングをオフにした方が効果的です。

    構成プロパティー mp.openapi.extensions.liberty.file.polling.interval は、更新がないかモニター対象ファイルをチェックする頻度を指定します。このプロパティーの値は、ゼロ以上の整数です。間隔の単位は秒です。デフォルト値は 2 秒です。この値を 0 に設定すると、ファイルのモニタリングは使用不可になります。
    構成は MicroProfile Config 仕様によって注入されます。
    注: このプロパティーの値は、mpOpenAPI-1.0 フィーチャーが有効にされている場合のみチェックされます。

トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_api_mpopenapi_custom.html