OpenAPI 仕様をサポートする openapi-3.0 フィーチャーを使用して、REST API 資料を生成できます。REST API を文書化し、パブリック API とプライベート API を指定し、アノテーション・スキャンを有効にすることを選択し、Web アプリケーションを Liberty サーバーにデプロイします。そうすると、openapi-3.0 によって生成された API 文書を、ユーザー・フレンドリーなユーザー・インターフェースを使用するブラウザーで表示できます。
始める前に
OpenAPI V3 仕様について学習してください。アプリケーション内の RESTful API を文書化するため、YAML ファイルまたは JSON ファイルを使用します。
このタスクについて
以下のサンプル・アプリケーションで、新しいユーザー・インターフェース、アノテーション、およびプログラミング・インターフェースなどの機能を探索することができます。
手順
- OpenAPI 文書をビルドします。
OpenAPI を文書化およびビルドする方法はいくつかあります。
- Liberty サーバー構成で openapi-3.0 フィーチャーを使用可能にします。
- openapi-3.0 フィーチャーをフィーチャー・マネージャーに追加します。
<server>
<featureManager>
<feature>openapi-3.0</feature>
</featureManager>
</server>
- オプション: アプリケーション OpenAPI がプライベートであることを指定します。
デフォルトでは、OpenAPI 文書はパブリックです。パブリック API にはすべてのユーザーがアクセスでき、認証を必要とせずにアクセスできることもよくあります。パブリック API は /api/docs リソース内に文書化されます。
API がプライベートなままになるよう指定することができます。管理用に使用される API は通常はプライベートのままにされます。
プライベート API は、保護のためにパスワードを使用し、/ibm/api/docs リソース内に文書化されます。このリソースは、すべてのプライベート API およびすべてのパブリック API を文書化します。
次の 2 つの方法で、Web アプリケーションのプライベート API を指定できます。
- サーバー構成内で、public 属性を false に設定して webModuleDoc を使用します。
- openapi エレメントを追加し、その enablePrivateURL ブール属性を true に設定します。
- 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>
デフォルトでは、webModuleDoc の public 属性は true に設定されます。この構成が必要なのは、プライベートなままにしたいアプリケーションを使用不可にする場合のみです。
- API 記述でベンダー拡張キーワードを使用して、API がプライベートであることを指定します。
- サーバー構成に openapi エレメントを追加し、その enablePrivateURL ブール属性を true に設定します。
- x-ibm-private: true キーワードと値を、API 記述文書 META-INF/openapi.yaml ファイル、または、別のサポートされるフォーマットのファイル内に置きます。この値は API のデフォルトの可視性をオーバーライドし、webModuleDoc 項目はこの値をオーバーライドできます。
- オプション: 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 属性はサポートされません。
- オプション: 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) を使用してアクセスできます。
- 特定のアプリケーションに対して、サード・パーティー API の可視性を許可します。 OpenAPI アノテーション、モデル、およびプログラミング・モデルの実行時ロードを使用可能にするには、特定のアプリケーションに対してサード・パーティー API 可視性を有効にする必要があります。
- サード・パーティー API 可視性として、classloader エレメントの apiTypeVisibility 属性を定義します。server.xml ファイル内の classloader エレメントに third-party を追加します。
apiTypeVisibilityに third-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>
- オプション: OpenAPI 文書の検証を使用可能にします。
検証機能は、デフォルトでは使用不可になります。検証を使用可能にすると、アプリケーションによって提供される各 OpenAPI 文書は、openapi-3.0 フィーチャーによって、OpenAPI V3 仕様で宣言された制約に照らして検証されます。openapi-3.0 フィーチャーは、無効な OpenAPI 文書を検出すると、違反があった制約ごとにエラーをログに記録します。無効な文書は、api/docs エンドポイントによって返される集約 OpenAPI 文書から除外されます。検証を使用可能にするには、server.xml ファイル内で validation 属性を true に設定します。
<openapi validation="true"/>
- アプリケーションをデプロイします。
- 生成された 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 で文書を表示します。
ヒント: デフォルトでは、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 エンドポイントを表示できます。表示されたエンドポイントをフィルター操作して、特定のアプリケーションにフォーカスすることもできます。