[17.0.0.3 and later]

OpenAPI を使用した REST API 資料の生成

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

始める前に

OpenAPI V3 仕様について学習してください。アプリケーション内の RESTful API を文書化するため、YAML ファイルまたは JSON ファイルを使用します。

[18.0.0.1 and later]重要:

MicroProfile OpenAPI 仕様バージョン 1.0 から入手可能な Java インターフェースおよびプログラミング・モデルを使用することができます。mpOpenAPI-1.0 フィーチャーは、MicroProfile OpenAPI 仕様を実装します。

mpOpenAPI-1.0 フィーチャーについて詳しくは、『MicroProfile OpenAPI 1.0 を使用した REST API 資料の生成』を参照してください。

このタスクについて

以下のサンプル・アプリケーションで、新しいユーザー・インターフェース、アノテーション、およびプログラミング・インターフェースなどの機能を探索することができます。

手順

  1. OpenAPI 文書をビルドします。

    OpenAPI を文書化およびビルドする方法はいくつかあります。

    • Java コードで OpenAPI アノテーションを指定して、アプリケーションを拡張および文書化します。
    • テキスト・エディターを使用して OpenAPI タグで API を文書化し、次に、完成した openapi.yaml ファイル、openapi.yml ファイル、または openapi.json ファイルを、アプリケーションの META-INF ディレクトリーに入れます。
    • io.swagger.oas.integration.OpenAPIConfigurationBuilder プログラミング・インターフェースを使用して、アプリケーション内から OpenAPI モデルをビルドします。このインターフェース、および、OpenAPI V3 用のその他の関連プログラミング・インターフェースは、 /wlp/dev/api/third-party ディレクトリー内の JAR ファイルにあります。openapi-3.0 フィーチャーが OpenAPIConfigurationBuilder を開始するには、アプリケーション・アーカイブに META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder ファイルがある必要があります。 このファイルの内容は、OpenAPIConfigurationBuilder の完全修飾名です。

      使用可能なプログラミング・インターフェース、それらの機能説明と使用例について詳しくは、『OpenAPI V3 プログラミング・インターフェース』を参照してください。

  2. Liberty サーバー構成で openapi-3.0 フィーチャーを使用可能にします。
    1. openapi-3.0 フィーチャーをフィーチャー・マネージャーに追加します。
      <server>
         <featureManager>
            <feature>openapi-3.0</feature>
         </featureManager>
      </server>
    2. オプション: アプリケーション OpenAPI がプライベートであることを指定します。

      デフォルトでは、OpenAPI 文書はパブリックです。パブリック API にはすべてのユーザーがアクセスでき、認証を必要とせずにアクセスできることもよくあります。パブリック API は /api/docs リソース内に文書化されます。

      API がプライベートなままになるよう指定することができます。管理用に使用される API は通常はプライベートのままにされます。 プライベート API は、保護のためにパスワードを使用し、/ibm/api/docs リソース内に文書化されます。このリソースは、すべてのプライベート API およびすべてのパブリック API を文書化します。

      次の 2 つの方法で、Web アプリケーションのプライベート API を指定できます。

      • サーバー構成内で、public 属性を false に設定して webModuleDoc を使用します。
        1. openapi エレメントを追加し、その enablePrivateURL ブール属性を true に設定します。
        2. Web アプリケーションごとに 1 つの webModuleDoc サブエレメントを追加し、その public ブール属性を、パブリック API の場合は true に、プライベート API の場合は false に設定します。

        次の例では、airlines アプリケーション OpenAPI を可視化し、airlinesAdmin アプリケーション OpenAPI の公開を無効にしています。

        <openapi enablePrivateURL="true">
          <webModuleDoc contextRoot="/airlines" public="true" />
          <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
        </openapi>

        デフォルトでは、webModuleDocpublic 属性は true に設定されます。この構成が必要なのは、プライベートなままにしたいアプリケーションを使用不可にする場合のみです。

      • API 記述でベンダー拡張キーワードを使用して、API がプライベートであることを指定します。
        1. サーバー構成に openapi エレメントを追加し、その enablePrivateURL ブール属性を true に設定します。
        2. x-ibm-private: true キーワードと値を、API 記述文書 META-INF/openapi.yaml ファイル、または、別のサポートされるフォーマットのファイル内に置きます。この値は API のデフォルトの可視性をオーバーライドし、webModuleDoc 項目はこの値をオーバーライドできます。
    3. オプション: OpenAPI 文書にアプリケーションが表示されないことを指定します。

      デフォルトでは、REST API 資料を含んでいる Web モジュールは、/api/docs リソース内にあるマージされた OpenAPI 文書に表示されます。Web モジュールが OpenAPI 文書に表示されないようにするには、サーバー構成内で webModuleDoc エレメントの属性を変更します。

      contextRoot 属性を使用して、非表示または表示する Web モジュールを特定します。次に、enabled 属性を false に変更して、OpenAPI 文書で Web モジュールを非表示にします。enabled 属性のデフォルト値は true です。次の例では、airlines モジュールは OpenAPI 文書に表示されるように構成され、airlinesAdmin モジュールは非表示にされています。

      <openapi>
        <webModuleDoc contextRoot="/airlines" enabled="true" />
        <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
      </openapi>
      注: 他の Liberty フィーチャーによって提供される REST API 資料には、enabled 属性はサポートされません。
  3. オプション: JAX-RS アノテーション・スキャンを有効にします。

    jaxrs-2.0 フィーチャーをフィーチャー・マネージャーに追加します。jaxrs-2.0 フィーチャーと openapi-3.0 フィーチャーの両方がサーバーで有効にされている場合、アノテーション・スキャナーは、サーバー構成でスキャンが無効にされていない限り、サーバーにデプロイされているすべての Web アプリケーションをスキャンします。スキャナーは、クラス定義に OpenAPI 3.0 のアノテーションが付けられていて、かつ、@Path JAX-RS アノテーションが付けられているすべてのクラスを調べます。生成された OpenAPI 文書には、OpenAPI パブリック・エンドポイント (api/docs) およびプライベート・エンドポイント (ibm/api/docs) を使用してアクセスできます。

  4. 特定のアプリケーションに対して、サード・パーティー API の可視性を許可します。 OpenAPI アノテーション、モデル、およびプログラミング・モデルの実行時ロードを使用可能にするには、特定のアプリケーションに対してサード・パーティー API 可視性を有効にする必要があります。
    1. サード・パーティー API 可視性として、classloader エレメントの apiTypeVisibility 属性を定義します。server.xml ファイル内の classloader エレメントに third-party を追加します。

      apiTypeVisibilitythird-party を含めるための classloader が指定されていない場合、spec および ibm-api のデフォルト定義が使用されます。

      <application id="scholar" name="Scholar" type="ear" location="scholar.ear">
        <classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
      </application>
  5. オプション: OpenAPI 文書の検証を使用可能にします。

    検証機能は、デフォルトでは使用不可になります。検証を使用可能にすると、アプリケーションによって提供される各 OpenAPI 文書は、openapi-3.0 フィーチャーによって、OpenAPI V3 仕様で宣言された制約に照らして検証されます。openapi-3.0 フィーチャーは、無効な OpenAPI 文書を検出すると、違反があった制約ごとにエラーをログに記録します。無効な文書は、api/docs エンドポイントによって返される集約 OpenAPI 文書から除外されます。検証を使用可能にするには、server.xml ファイル内で validation 属性を true に設定します。

    <openapi validation="true"/>
  6. アプリケーションをデプロイします。
  7. 生成された API 文書をブラウザーで表示します。

    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 で文書を表示します。
    [17.0.0.4 and later]ヒント: デフォルトでは、1 つのサーバーに 2 つのエンドポイントが使用可能です。
    • GET http://Liberty_host:http_port/api/docs
    • GET http://Liberty_host:http_port/api/explorer
    server.xml ファイル内の publicURL 属性を使用して、パブリック・エンドポイントの URL をカスタマイズできます。次の例は、パブリック REST API 資料を GET http://Liberty_host:http_port/myAPI/docs および http://Liberty_host:http_port/myAPI/explorer で使用可能にするための server.xml ファイル内の構成を示しています。
    <openapi publicURL="myAPI" />

    OpenAPI 文書が生成され、その Liberty サーバーのアプリケーションすべてにわたって集約されます。この文書はデフォルトでは YAML フォーマットです。文書を Microsoft Internet Explorer 11 で表示すると、正しくフォーマットされていない YAML 文書が返されます。回避策として、Mozilla Firefox または Google Chrome ブラウザーなどのブラウザーを使用してください。http 要求の Accept ヘッダーに application/json 値が指定されている場合、文書は 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 でユーザー・フレンドリーな UI を表示します。 SSL を有効にする場合、保護された UI に https://Liberty_host:https_port/api/explorer でアクセスできます。

server.xml ファイルの openAPI エレメント内の enablePrivateURL 属性を有効にすることによって、プライベート Web モジュールを表示できます。
<openapi enablePrivateURL="true"/>
プライベート Web モジュールの表示が使用可能にされている場合、https://Liberty_host:https_port/ibm/api/explorer を使用して、パブリックとプライベート両方の Web モジュール用のユーザー・フレンドリーな UI を表示できます。

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


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

ファイル名: twlp_api_openapi.html