Liberty サーバー上の REST API 資料のディスカバー
![[18.0.0.1 and later]](../ng_v18001plus.gif)
手順
- 使用可能な REST API を検出したい Liberty サーバーの server.xml ファイル内で、フィーチャー・マネージャーに apiDiscovery-1.0 フィーチャーを追加します。
apiDiscovery-1.0 フィーチャーによって、製品で REST API ディスカバリー・バンドルが使用可能になります。また、このフィーチャーは、Liberty REST エンドポイント (例えば、JMX (サーバー構成で restConnector-1.0 フィーチャーが使用されている場合) や集合 (サーバー構成で collectiveController-1.0 フィーチャーが使用されている場合)) からドキュメンテーションを表示します。
Liberty 集合コントローラー・サーバー上で有効にされた apiDiscovery-1.0 フィーチャーは、そのコントローラー上と、そのメンバー・サーバーのうち apiDiscovery-1.0 フィーチャーが有効にされたメンバー・サーバー上で、使用可能な REST API を検出します。
デプロイされたアプリケーションに必要なすべてのフィーチャー (jaxrs-2.0 など) がサーバー構成に指定されていることを確認してください。サーバーが HTTP ポートを開くことができるように、ポートを変更します。
プライベート REST API 資料を表示する場合は、server.xml ファイルで鍵ストア・サービス・オブジェクト項目およびユーザー・レジストリー設定を構成します。
ただし、パブリック REST API 資料のみを表示するときには、HTTPS を介して文書にアクセスする場合にのみ、鍵ストア・オブジェクト項目を追加します。 HTTP を介したパブリック文書へのアクセスには、鍵ストア・オブジェクト項目もユーザー・レジストリー設定も不要です。
以下の server.xml ファイルには apiDiscovery-1.0 フィーチャーが含まれています。
<server> <featureManager> <feature>apiDiscovery-1.0</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="8010" httpsPort="8020"/> <keyStore id="defaultKeyStore" password="Liberty"/> <basicRegistry id="basic" realm="ibm/api"> <user name="bob" password="bobpwd" /> </basicRegistry> </server>
- Liberty REST エンドポイントで Swagger 2.0 文書を表示します。
Web アプリケーションに javax.ws.rs.core.Application クラスの 2 個以上のインスタンスが含まれていて、API Discovery フィーチャーと正しく連動する場合、各アプリケーションは web.xml ファイルに固有の javax.ws.rs.@ApplicationPath 値または URL マッピング が定義されている必要があります。
apiDiscovery-1.0 フィーチャーを有効にして、アノテー ション・スキャン中に検出されたドキュメンテーションと、現行のド キュメンテーションをマージすることが可能です。 Web モジュールで META-INF/stub/swagger.json ファイルまたは META-INF/stub/swagger.yaml ファイルが検索されます。 フィーチャーによってこれらのファイルのいずれかが検出されると、そのフ ァイルの内容と、Web モジュール内の JAX-RS および Swagger アノテーショ ンの両方が入った Swagger 文書が生成されます。 ドキュメンテーションは JAX-RS の部分と自動的にマージされるため、このフィーチャーを使用して、JAX-RS 以外のサーブレットを文書化できます。 API ドキュメンテーションのロケーションは次の 2 つの方法のいずれかで構成できます。
- SPI com.ibm.wsspi.rest.api.discovery.APIProvider インターフェースの getDocument メソッドを使用します。
getDocument メソッドにより、拡張フィーチャーからの OSGi バンドルが全体的なマスター文書に対して REST API 資料を提供できるようになります。このリリースでは、サポートされている DocType は DocType.Swagger_20_JSON と DocType.Swagger_20_YAML のみです。 このインターフェースのインプリメンターは、直列化された JSON または YAML 文書を java.lang.String 値として返すか、 あるいは、JSON または YAML ファイル・ロケーションへのファイル参照 (接頭部は file:///) を渡すことができます。
- デプロイされた Web アプリケーションを使用します。
各 Web モジュールは独自の REST API 資料を提供できます。 1 つのエンタープライズ・アプリケーション (EAR) ファイル内の複数の WAR ファイルが、異なる Swagger 2.0 文書を保持できます。
Web モジュールのドキュメンテーションを表示する最も簡単な方法は、 対応する META-INF フォルダーに swagger.json ファイルまたは swagger.yaml ファイルを含めることです。アプリケーションのデプロイ中に、 API Discovery フィーチャーが各 Web モジュールの META-INF/swagger.json 値を探します。 META-INF/swagger.json 値が見つからない場合、API Discovery フィーチャーが META‐INF/swagger.yaml 値を探します。
Web モジュールの REST API 資料を表示する別の方法は、 server.xml 構成ファイルでの方法です。Web モジュールごとに webModuleDoc エレメントを親 apiDiscovery エレメント内に置きます。以下に例を示します。
<apiDiscovery> <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" /> <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" /> <webModuleDoc contextRoot="/custom" enabled="true" docURL="http://petstore.swagger.io/v2/swagger.json" /> </apiDiscovery>
webModuleDoc エレメントには、どの Web モジュールのドキュメンテーションを表示するのかを一意的に示す contextRoot 属性が指定される必要があります。
オプション属性 enabled は、Web モジュールの API ディスカバリーを切り替えます。この属性のデフォルトは true です。
docURL 属性は、Web モジュールのドキュメンテーションが見つかる場所を指定します。docURL 値は、例えば /30ExampleServletInEar/swagger.json のように、 URL がコンテキスト・ルートに相対的になるようにスラッシュ (/) で始めることができます。あるいは、docURL 値を http または https で始めて、ドキュメンテーションの完全なロケーションを示す絶対 URL を指定することもできます。
Web アプリケーションが swagger.json ファイルおよび swagger.yaml ファイルを提供せず、 JAX-RS アノテーション付きリソースを含んでいる場合、自動的に Swagger 文書を生成することができます。サーバー構成には apiDiscovery-1.0 フィーチャーと、 jaxrs-1.1 または jaxrs-2.0 フィーチャーが含まれている必要があります。 以下に例を示します。
Web アプリケーション内のすべてのクラスで JAX-RS アノテーションおよび Swagger アノテーションがないかスキャンされ、 @Path、@Api、および @SwaggerDefinition アノテーションが付いたクラスが探されます。また、Web アプリケーションのデプロイ中または始動中に、該当の Swagger 文書が製品によって自動的に生成されます。<featureManager> <feature>apiDiscovery-1.0</feature> <feature>jaxrs-1.1</feature> </featureManager>
apiDiscovery-1.0 フィーチャーを使用して、アノテーション・スキャン中に検出されたドキュメンテーションと、前に生成されたドキュメンテーションをマージすることも可能です。 Web モジュールで META-INF/stub/swagger.json ファイルまたは META-INF/stub/swagger.yaml ファイルが検索されます。 フィーチャーによってこれらのファイルのいずれかが検出されると、そのフ ァイルの内容と、Web モジュール内の JAX-RS および Swagger アノテーショ ンの両方が入った Swagger 文書が生成されます。 ドキュメンテーションは JAX-RS の部分と自動的にマージされるため、このフィーチャーを使用して、JAX-RS 以外のサーブレットを文書化できます。
この手法は、セキュリティー定義の表示など、アノテーションの制限 をバイパスするために使用することも可能です。例えば、META-INF/stub 内の以下の swagger.json により、アノテーションは該当する定義を参照できます。
{ "swagger" : "2.0", "securityDefinitions" : { "petstore_auth" : { "type" : "oauth2", "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog," "flow" : "implicit", "scopes" : { "write_pets" : "modify pets in your account", "read_pets" : "read your pets" } }, "api_key" : { "type" : "apiKey", "name" : "api_key", "in" : "header" } } }
- SPI com.ibm.wsspi.rest.api.discovery.APIProvider インターフェースの getDocument メソッドを使用します。
- API ドキュメンテーションをディスカバーします。
API ドキュメンテーションのロケーションを構成した後、それを以下の方法でディスカバーできます。
- GET
https://host:https_port/ibm/api/docs エンドポイントを使用します。
このエンドポイントは、 すべての使用可能な Liberty REST API をマージして 1 つの文書にした、有効な Swagger 2.0 文書を提供します。これは、 API 管理ソリューションなど、使用可能な API のセットをプログラマチックにナビゲートしたいコンシューマー・アプリケーションに便利です。 application/yaml 値を指定したオプションの Accept ヘッダーを組み込むと、YAML フォーマットで Swagger 2.0 文書が提供されます。このエンドポイントには、 1 つのマルチ・カーディナリティー、つまり、検出されるコンテキスト・ルートをフィルター処理できる root という名前のオプションの照会パラメーターがあります。例えば、GET https://host:https_port/ibm/api/docs?root=/myApp の呼び出しでは、myApp コンテキスト・ルートのドキュメンテーションのみを持つ Swagger 2.0 文書が取得されます。
- GET
https://host:https_port/ibm/api/explorer エンドポイントを使用します。
このエンドポイントは、 /ibm/api/docs URL からのコンテンツを表示する、レンダリングされた魅力的な HTML ページを提供します。このページは、ユーザーが REST API を開始することができるように、標準オンライン・サンプル (http://petstore.swagger.io/) と同じパターンに従います。このエンドポイントは、 Liberty サーバー上の使用可能な REST API を探索して、場合によってはそれらをページから開始するのに役立ちます。
ページ上のフィルター入力ボックスでは、コンテキスト・ルートのコンマ区切りリストによって コンテンツをフィルター操作することができます。
- 集合コントローラーの場合、
GET
https://host:https_port/ibm/api/collective/docs エンドポイントを使用します。
集合コントローラー上のこのエンドポイントは、 集合コントローラーからと、そのメンバーのうち apiDiscovery-1.0 フィーチャーが有効になっているメンバーから使用可能な REST API をマージして 1 つの文書にした、有効な Swagger 2.0 文書を提供します。これは、 API 管理ソリューションなど、使用可能な API のセットをプログラマチックにナビゲートしたいコンシューマー・アプリケーションに便利です。 application/yaml 値を指定したオプションの Accept ヘッダーを組み込むと、YAML フォーマットで Swagger 2.0 文書が提供されます。
このエンドポイントには、1 つのマルチ・カーディナリティーのオプション照会パラメーター root があります。
照会パラメーター root は、検出されるコンテキスト・ルートをフィルター操作できます。例えば、GET https://host:https_port/ibm/api/collective/docs?root=/myApp の呼び出しでは、myApp コンテキスト・ルートのドキュメンテーションのみを持つ Swagger 2.0 文書が取得されます。
17.0.0.1 より前のバージョンの場合、このエンドポイントには、2 つのマルチ・カーディナリティー、つまり、 root という名前と serverID という名前のオプションの照会パラメーターがあります。照会パラメーター root は前と同じです。照会パラメーター serverID は、Liberty サーバーから使用可能な REST API をフィルター操作できます。serverID のフォーマットは、 hostName,userDir,serverName です。 例えば、GET https://host:https_port/ibm/api/collective/docs?serverID=samplehost.com:8020,/users/admin/wlp/usr,server1 の呼び出しでは、 指定された serverID を持つ Liberty サーバーから使用可能な REST API のドキュメンテーションのみを持つ Swagger 2.0 文書が取得されます。
- 集合コントローラーの場合、GET
https://host:https_port/ibm/api/collective/explorer エンドポイントを使用します。
集合コントローラー上のこのエンドポイントは、 /ibm/api/collective/docs URL からのコンテンツを表示する、レンダリングされた魅力的な HTML ページを提供します。このエンドポイントは、 集合全体の使用可能な REST API を探索して、場合によってはそれらをページから開始するのに役立ちます。ページ上のフィルター入力ボックスでは、コンテキスト・ルートとサーバー ID のコンマ区切りリストによって コンテンツをフィルター操作することができます。サーバー ID のフォーマットは、 "hostName,userDir,serverName" です。 サーバー ID を囲む引用符 (") は必須です。「試す (Try it out)」ボタンを使用して API をテストするには、メンバー・サーバーの server.xml 内で Cross Origin Request Sharing (CORS) をセットアップする必要があります。
17.0.0.1 より前のバージョンの場合、API /IBMJMXConnectorREST/mbeanCount を提供するメンバー・サーバーの server.xml 内に、以下の例のようなスニペットが必要です。
<cors domain="/IBMJMXConnectorREST/mbeanCount" allowedOrigins="https://controller_hostname:https_port" allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS" allowedHeaders="Content-Type,api_key,Authorization" allowCredentials="true" />
CORS のセットアップについて詳しくは、Liberty サーバーでの Cross Origin Resource Sharing の構成を参照してください。
注: CORS の要件は、集合バージョンの Swagger UI (https://host:https_port/ibm/api/collective/explorer) にのみ適用されます。 他のエンドポイントを使用して、パブリック REST 文書を表示します。
前述のエンドポイントとは異なり、これらのエンドポイントにアクセスするには、鍵ストア・サービス・オブジェクト項目もユーザー・レジストリー設定も不要です。ただし、鍵ストア・サービス・オブジェクト項目を設定することで、HTTPS を介してエンドポイントにアクセスできます。
デフォルトでは、1 つの集合コントローラーに 4 つのエンドポイントが使用可能です。- GET http://host:http_port/api/docs
- GET http://host:http_port/api/explorer
- GET http://host:http_port/api/collective/docs
- GET http://host:http_port/api/collective/explorer
デフォルトでは、1 つのサーバーに 2 つのエンドポイントが使用可能です。- GET http://host:http_port/api/docs
- GET http://host:http_port/api/explorer
server.xml 内の publicURL 属性を使用して、パブリック・エンドポイントの URL を変更できます。例えば、server.xml で以下の構成を設定すると、パブリック REST API 資料が、GET http://host:http_port/myAPI/docs および http://host:http_port/myAPI/explorer で使用可能になります。
<apiDiscovery publicURL="myAPI" />
デフォルトでは、JMX REST Connector REST API などの内部サーバー・エンドポイントを除き、デプロイ済み Web アプリケーションによって提供されるすべての REST API エンドポイントが、パブリック REST API 資料に表示されます。Web モジュールの public="false" 属性を設定することで、モジュールによって表示される REST API を非表示にすることができます。例えば、以下の構成を server.xml に追加すると、Web モジュールによる REST API がパブリック REST API 資料で非表示になります。
<apiDiscovery publicURL="myAPI"> <webModuleDoc contextRoot="/22ExampleServlet" public="false" /> </apiDiscovery>
server.xml ファイル内の swaggerDefinition 属性を使用して、/docs エンドポイントで提供される Swagger 2.0 文書内の一部のフィールドを上書きします。
swaggerDefinition を使用して、上書きするフィールドが含まれた JSON または YAML の Swagger スニペットを指定できます。info フィールド、 schemes フィールド、consumes フィールド、produces フィールド、および externalDocs フィールドを上書きできます。
集合コントローラーの場合は、集合サービス照会を使用して、集合全体のすべての使用可能なパブリック RESTful API (サービス) をリストします。
apiDiscovery-1.0 フィーチャーを有効にしたら、 ObjectName 値 WebSphere:feature=apiDiscovery,name=APIDiscovery を持つ管理 Bean (MBean) が、Liberty MBeanServer に登録されます。 この MBean は以下の属性を提供しています。
- DocumentationURL 属性は、 /ibm/api/docs エンドポイントの完全 URL で、未加工の JSON または YAML ドキュメンテーションを表示します。
- ExplorerURL 属性は、 /ibm/api/explorer エンドポイントの完全 URL で、ドキュメンテーションのレンダリングされた UI を表示します。
この MBean を使用して、REST API ディスカバリーが有効かどうか、クライアントがどこでそれに到達できるかが分かります。
- GET
https://host:https_port/ibm/api/docs エンドポイントを使用します。
例
REST API ディスカバリーについて詳しくは、OpenAPI インターフェースおよび WASdev Web サイトを参照してください。
ご覧ください: IBM MediaCenter の IBM
WebSphere Application Server Liberty API Discovery ビデオでは、サンプルとデモンストレーション・ビデオへのリンクを提供しています。(V8.5.5.9)
サブトピック
Swagger 2.0 文書フィールドの上書き
server.xml ファイルで swaggerDefinition 属性を使用して、 /docs エンドポイントおよび /explorer エンドポイントによって提供される Swagger 2.0 文書内の一部のフィールドを上書きします。集合内のすべてのパブリック RESTful API のリスト
集合サービス照会を使用して、集合全体におけるすべてのパブリック RESTful API (サービス) に関する API 文書をディスカバーします。この照会では、文書がリスト形式で示されます。- Liberty REST API 更新のサブスクライブ
Liberty REST API ディスカバリー・フィーチャーは現在、新しい REST API /ibm/api/docs/subscription を公開しています。これにより、新規の API が利用可能になる、古い API が削除されるといった REST API 更新をユーザーがサブスクライブすることができます。 特定の Liberty インスタンスで提供されるエンドポイントでの変更をすぐに通知してほしい場合に、これは便利です。 - 集合内の Liberty REST API 更新のサブスクライブ
集合コントローラーでサブスクリプション API を使用して、新しい REST API、削除された API、または API の変更 (特定集合メンバー・サーバーのエンドポイントでの変更など) について即時に知ることができます。 - IBM API Connect に API をプッシュするための REST エンドポイント
REST エンドポイントは、オンプレミスとクラウドの両方の Liberty ユーザーにとってのセントラル・ロケーションであり、API の視覚化、呼び出し、および IBM® API Connect へのプッシュに使用することができます。

ファイル名: twlp_api_discovery.html