Liberty サーバー上の REST API ドキュメンテーションのディスカバー
API ディスカバリー・フィーチャーを使用して、使用可能な REST API を検出することで、Liberty サーバー上の REST API 資料をディスカバーできます。Swagger ユーザー・インターフェースを使用して、使用可能な REST エンドポイントを呼び出します。
手順
- 使用可能な REST API を検出したい Liberty サーバーの server.xml ファイル内で、フィーチャー・マネージャーに apiDiscovery-1.0 フィーチャーを追加します。
apiDiscovery-1.0 フィーチャーによって、製品で REST API ディスカバリー・バンドルが使用可能になります。また、このフィーチャーは、Liberty REST エンドポイント (例えば、JMX (サーバー構成で restConnector-1.0 フィーチャーが使用されている場合) や集合 (サーバー構成で collectiveController-1.0 フィーチャーが使用されている場合)) からドキュメンテーションを公開します。
デプロイされたアプリケーションに必要なすべてのフィーチャー (servlet-3.0 や jsp-2.2 など) がサーバー構成に指定されていることを確認してください。また、デプロイされたアプリケーションにとって、ポートおよびユーザー・レジストリーの設定が正しいことも確認してください。
以下の 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.0</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 を探索して、場合によってはそれらをページから起動するのに役立ちます。ページ上のフィルター入力ボックスでは、コンテキスト・ルートのコンマ区切りリストによって コンテンツをフィルター操作することができます。このフィルター操作は、 root 照会パラメーターと同様の働きをします。必要な入力値を指定して 「試す (Try it out)」をクリックすることで、API をテスト駆動できます。
- 集合コントローラーの場合、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) をセットアップする必要があります。
例えば、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 Request Sharing の構成を参照してください。
注: CORS の要件は、集合バージョンの Swagger UI (https://host:https_port/ibm/api/collective/explorer) にのみ適用できます。
- DocumentationURL 属性は、 /ibm/api/docs エンドポイントの完全 URL で、未加工の JSON または YAML ドキュメンテーションを表示します。
- ExplorerURL 属性は、 /ibm/api/explorer エンドポイントの完全 URL で、ドキュメンテーションのレンダリングされた UI を表示します。
この MBean を使用して、REST API ディスカバリーが有効かどうか、クライアントがどこでそれに到達できるかが分かります。
- GET
https://host:https_port/ibm/api/docs エンドポイントを使用します。
サブトピック
- Liberty REST API 更新のサブスクライブ
Liberty REST API ディスカバリー・フィーチャーは現在、新しい REST API /ibm/api/docs/subscription を公開しています。これにより、新規の API が利用可能になる、古い API が削除されるといった REST API 更新をユーザーがサブスクライブすることができます。 特定の Liberty インスタンスで提供されるエンドポイントでの変更をすぐに通知してほしい場合に、これは便利です。 - IBM API Connect に API をプッシュするための REST エンドポイント
REST エンドポイントは、オンプレミスとクラウドの両方の Liberty ユーザーにとってのセントラル・ロケーションであり、API の視覚化、呼び出し、および IBM® API Connect へのプッシュに使用することができます。


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-libcore-mp&topic=twlp_api_discovery
ファイル名: twlp_api_discovery.html