REST API 資料の集約

MicroProfile OpenAPI 仕様をサポートする openapi-3.1 フィーチャーを使用して、生成された REST API 資料を集約できます。 REST API を文書化し、パブリック API とプライベート API を指定し、Web アプリケーションを Liberty サーバーにデプロイします。 そうすると、openapi-3.1 によって生成された API 文書を、ユーザー・フレンドリーなユーザー・インターフェースを使用するブラウザーで表示できます。

安定化されたフィーチャー: openapi-3.1 フィーチャーは安定化されました。 フィーチャーを引き続き使用できます。 ただし、戦略的な代替手段は、 mpOpenAPI-3.0などのMicro Profile Open API機能を使用することです。

始めに

openapi-3.1 フィーチャーは、MicroProfile OpenAPI 仕様を実装する mpOpenAPI-1.0 フィーチャーの拡張機能です。 mpOpenAPI-1.0 フィーチャーについて詳しくは、 Generating REST API documentation with MicroProfile OpenAPI 1.0を参照してください。

手順

  1. OpenAPI 文書をビルドします。 資料の作成手順については、 Generating REST API documentation with MicroProfile OpenAPI を参照してください。
  2. Liberty サーバー構成で openapi-3.1 フィーチャーを使用可能にします。
    1. openapi-3.1 フィーチャーをフィーチャー・マネージャーに追加します。
      <server>
   <featureManager>
      <feature>openapi-3.1</feature>
   </featureManager>
</server>
    2. オプション: アプリケーション OpenAPI がプライベートであることを指定します。 デフォルトでは、OpenAPI 文書はパブリックです。 パブリック API にはすべてのユーザーがアクセスでき、認証を必要とせずにアクセスできることもよくあります。 パブリック API については、 /api/docs resourceに記載されています。 API がプライベートなままになるよう指定することができます。 管理用に使用される API は通常はプライベートのままにされます。 プライベート API は、保護のためにパスワードを使用し、/ibm/api/docs リソース内に文書化されます。 このリソースは、すべてのプライベート API およびすべてのパブリック API を文書化します。 MicroProfile 構成プロパティー、mp.openapi.extensions.liberty.public=false をアプリケーション・レベルで設定することで、Web アプリケーション用のプライベート API を指定できます。 デフォルトでは、このプロパティーの値は TRUE です。 この構成が必要なのは、プライベートなままにしたいアプリケーションを使用不可にする場合のみです。
    3. オプション: OpenAPI 文書にアプリケーションが表示されないことを指定します。 デフォルトでは、REST API 資料を含んでいる Web モジュールは、/api/docs リソース内にあるマージされた OpenAPI 文書に表示されます。 Web モジュールが OpenAPI 文書に表示されないようにするには、MicroProfile 構成プロパティー mp.openapi.extensions.liberty.exclude.context.roots の値を設定します。 このプロパティーの値は、非表示にするコンテキスト・ルートをコンマで区切ったリストです。 非表示にする各 Web モジュールをコンテキスト・ルートで特定し、それらのコンテキスト・ルートをプロパティーの値に追加します。 例えば、コンテキスト・ルートが /airlinesAdmin の Web モジュールを非表示にするには、mp.openapi.extensions.liberty.exclude.context.roots=/airlinesAdmin のように設定します。 このプロパティーは、 openapi-3.1 フィーチャーが有効になっている場合に読み取られます。
  3. アプリケーションをデプロイします。
  4. API がパブリックかプライベートかに応じて、以下のいずれかの URL を使用して、生成された API 文書を /api/docs エンドポイントで見つけることができます。
      • 非 SSL パブリック API の場合は、http://Liberty_host:http_port/api/docs で文書を表示します。
      • SSL パブリック API の場合は、https://Liberty_host:https_port/api/docs で文書を表示します。
      • SSL プライベート API の場合は、https://Liberty_host:https_port/ibm/api/docs で文書を表示します。
    ヒント：
    デフォルトでは、1 つのサーバーに 2 つのエンドポイントが使用可能です。
      • GET http://Liberty_host:http_port/api/docs
      • GET http://Liberty_host:http_port/api/explorer
    MicroProfile 構成プロパティー mp.openapi.extensions.liberty.public.url を使用して、パブリック・エンドポイントの URL をカスタマイズできます。 このプロパティーは、openapi-3.1 フィーチャーが使用可能である場合に読み取られます。 次の例は、パブリック REST API 資料を GET http://Liberty_host:http_port/myAPI/docs および http://Liberty_host:http_port/myAPI/explorer で使用可能にするための MicroProfile 構成を示しています。
    mp.openapi.extensions.liberty.public.url=myAPI

    OpenAPI 文書が生成され、その Liberty サーバーのアプリケーション間で集約されます。 この文書はデフォルトでは YAML フォーマットです。 HTTP 要求の Accept ヘッダーに application/json 値が指定されている場合、文書は JSON フォーマットです。 あるいは、フォーマット照会パラメーター http://Liberty_host:http_port/api/docs?format=json を使用することもできます。

    ヒント：

    OpenAPI 文書をコンテキスト・ルートでフィルター操作できます。 パブリック・エンドポイント (api/docs) とプライベート・エンドポイント (ibm/api/docs) の両方が、検出されたコンテキスト・ルートをフィルター操作できる照会パラメーター root をサポートしています。 例えば、

    GET http://Liberty_host:http_port/api/docs?root=/myApp は、 myApp コンテキスト・ルートの文書のみを含む OpenAPI V3 文書を取得します。

結果

OpenAPI ユーザー・インターフェースは、 /api/docs から集約された定義を http://Liberty_host:http_port/api/explorerにレンダリングします。 SSL を有効にする場合、保護された UI に https://Liberty_host:https_port/api/explorer でアクセスできます。

MicroProfile 構成プロパティー mp.openapi.extensions.liberty.enable.private.url=true を設定することによって、プライベート Web モジュールを表示できます。 このプロパティーは、openapi-3.1 フィーチャーが使用可能である場合に読み取られます。

プライベート Web モジュールの表示が使用可能にされている場合、https://Liberty_host:https_port/ibm/api/explorer を使用して、パブリックとプライベート両方の Web モジュール用のユーザー・フレンドリーな UI を表示できます。

このユーザー・インターフェースで、アプリケーションからのすべての RESTful エンドポイントを表示できます。 表示されたエンドポイントをフィルター操作して、特定のアプリケーションにフォーカスすることもできます。