OpenAPI 文書のカスタマイズ

/api/docs エンドポイントで使用可能なメイン OpenAPI 文書および /api/explorer の OpenAPI ユーザー・インターフェースのさまざまな局面を、externalDocs や info などのエレメントを使用してカスタマイズできます。 Liberty は、メインの OpenAPI 文書および UI に対する変更を処理および更新するために、デフォルトのパス・ロケーションにあるカスタマイズ・ファイルに対する変更をモニターします。

安定化されたフィーチャー: OpenAPI V3 フィーチャー ( openapi-3.0 および openapi-3.1) は安定化されました。 フィーチャーを引き続き使用できます。 ただし、戦略的な代替手段は、 mpOpenAPI-3.0などの MicroProfile OpenAPI フィーチャーを使用することです。

始めに

OpenAPI 資料を作成して有効にする方法については、 OpenAPIを参照してください。

サンプル OpenAPI V3 航空会社アプリケーションを使用して、文書を生成し、カスタマイズ可能な UI の例をレンダリングします。

手順

  1. 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) 値に設定されたロゴ・イメージを参照する必要があります。
    次のスニペット例は、オーバーライドする CSS ファイルを示しています。
    .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;
}
  2. カスタマイズ・ファイルのファイル・モニタリングを構成します。

    カスタマイズ・ファイルを自動モニタリングのためにデフォルト・ロケーションに保存するか、または、サーバー構成を変更してファイルのロケーションを定義することができます。 複数のデフォルト・カスタマイズ・ファイルが指定されている場合、モニターされるカスタマイズ・ファイルと無視されるカスタマイズ・ファイルを示す警告メッセージ出力がコンソールに表示されます。 モニター対象として選択されたカスタマイズ・ファイルは、削除されるまで Liberty によって継続的にモニターされます。

    注: 更新がモニターされるのは、カスタマイズ・ファイルのみです。 CSS ファイルおよびロゴ・ファイルはモニターされません。 URL はモニターされません。
    1. デフォルトのカスタマイズ・ファイル・モニターを使用するには、 ${server.config.dir}/openapi/customization.file_type にある YAML、YML、または JSON のいずれかのファイル・タイプでカスタマイズ・スニペットを保存します。
    2. オプション: 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" />
  3. オプション: カスタマイズ・ファイルのファイル・モニターを無効にします。

    Liberty は、デフォルトでカスタマイズ・ファイルを継続的にモニターします。 しかし、ファイルのモニタリングはシステム・リソースを余分に使用します。 カスタマイズ・ファイルがない場合、または、カスタマイズ・ファイルが静的であって変更されない場合は、ファイル・モニタリングをオフにした方が効果的です。

    サーバー構成ファイルで、 openapi エレメントの disableFileMonitor ブール属性を true に設定します。 disableFileMonitor 属性が true に設定されている場合、デフォルトのカスタマイズ定義ロケーションもモニターされません。
    
<openapi disableFileMonitor="true" />