Liberty サーバー上の REST API ドキュメンテーションのディスカバー

API ディスカバリー・フィーチャーを使用して、使用可能な REST API を検出することで、Liberty サーバー上の REST API 資料をディスカバーできます。Swagger ユーザー・インターフェースを使用して、使用可能な REST エンドポイントを呼び出します。

手順

  1. 使用可能な REST API を検出したい Liberty サーバーの server.xml ファイル内で、フィーチャー・マネージャーに apiDiscovery-1.0 フィーチャーを追加します。

    apiDiscovery-1.0 フィーチャーによって、製品で REST API ディスカバリー・バンドルが使用可能になります。また、このフィーチャーは、Liberty REST エンドポイント (例えば、JMX (サーバー構成で restConnector-1.0 フィーチャーが使用されている場合) や集合 (サーバー構成で collectiveController-1.0 フィーチャーが使用されている場合)) からドキュメンテーションを公開します。

    デプロイされたアプリケーションに必要なすべてのフィーチャー (servlet-3.0jsp-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>
  2. 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_JSONDocType.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 フィーチャーが含まれている必要があります。 以下に例を示します。
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.0</feature>
      </featureManager>
      Web アプリケーション内のすべてのクラスで JAX-RS アノテーションおよび Swagger アノテーションがないかスキャンされ、 @Path@Api、および @SwaggerDefinition アノテーションが付いたクラスが探されます。また、Web アプリケーションのデプロイ中または始動中に、該当の Swagger 文書が製品によって自動的に生成されます。

      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"
          }
        }
      }
  3. 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 をテスト駆動できます。

    apiDiscovery-1.0 フィーチャーを有効にしたら、 ObjectNameWebSphere: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 ディスカバリーが有効かどうか、クライアントがどこでそれに到達できるかが分かります。


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



タイム・スタンプ・アイコン 最終更新: Tuesday, 6 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_api_discovery
ファイル名: twlp_api_discovery.html