Liberty サーバー上の REST API 資料のディスカバー

API ディスカバリー・フィーチャーを使用して、使用可能な REST API を検出することで、Liberty サーバー上の REST API 資料をディスカバーできます。Swagger ユーザー・インターフェースを使用して、使用可能な REST エンドポイントを開始します。
[18.0.0.1 and later]ヒント: REST API 資料をディスカバーするために openapi-3.0 フィーチャーを使用することができます。openapi-3.0 フィーチャーは、apiDiscovery-1.0 フィーチャーの次のバージョンであると分類できます。apiDiscovery-1.0 で作成された Swagger V2 文書を OpenAPI V3 に更新できます。 OpenAPI を使用した REST API 資料の生成を参照してください。

手順

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

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

    デプロイされたアプリケーションに必要なすべてのフィーチャー (jaxrs-2.0 など) がサーバー構成に指定されていることを確認してください。サーバーが HTTP ポートを開くことができるように、ポートを変更します。

    プライベート REST API 資料を表示する場合は、server.xml ファイルで鍵ストア・サービス・オブジェクト項目およびユーザー・レジストリー設定を構成します。

    [17.0.0.1 and later]ただし、パブリック 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>
  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.1</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 を探索して、場合によってはそれらをページから開始するのに役立ちます。

      ページ上のフィルター入力ボックスでは、コンテキスト・ルートのコンマ区切りリストによって コンテンツをフィルター操作することができます。

    • [17.0.0.1 and later]他のエンドポイントを使用して、パブリック REST 文書を表示します。

      前述のエンドポイントとは異なり、これらのエンドポイントにアクセスするには、鍵ストア・サービス・オブジェクト項目もユーザー・レジストリー設定も不要です。ただし、鍵ストア・サービス・オブジェクト項目を設定することで、HTTPS を介してエンドポイントにアクセスできます。

      デフォルトでは、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>
    • [17.0.0.1 and later]server.xml ファイル内の swaggerDefinition 属性を使用して、/docs エンドポイントで提供される Swagger 2.0 文書内の一部のフィールドを上書きします。

      swaggerDefinition を使用して、上書きするフィールドが含まれた JSON または YAML の Swagger スニペットを指定できます。info フィールド、 schemes フィールド、consumes フィールド、produces フィールド、および externalDocs フィールドを上書きできます。

    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 ディスカバリーが有効かどうか、クライアントがどこでそれに到達できるかが分かります。

REST API ディスカバリーについて詳しくは、OpenAPI インターフェースおよび WASdev Web サイトを参照してください。

音声プレゼンテーションの IBM MediaCenter Flash ビデオ ご覧ください: IBM MediaCenter の IBM WebSphere Application Server Liberty API Discovery ビデオでは、サンプルとデモンストレーション・ビデオへのリンクを提供しています。(V8.5.5.9)


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

ファイル名: twlp_api_discovery.html