[17.0.0.3 and later]

OpenAPI 文書のカスタマイズ

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

始める前に

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

サンプル OpenAPI V3 airlines アプリケーションを使用して、文書を生成し、カスタマイズ可能な 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. デフォルトのカスタマイズ・ファイル・モニタリングを使用するため、カスタマイズ・スニペットを、YAML、YML、または JSON ファイル・タイプで ${server.config.dir}/openapi/customization.file_type に保存します。
    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" />

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

ファイル名: twlp_api_openapi_custom.html