mpOpenAPI-1.0 フィーチャーは、MicroProfile
OpenAPI 仕様バージョン 1.0 の実装を提供します。また Java 開発者が
JAX-RS アプリケーションから OpenAPI v3 文書をネイティブに製造できる、一連の Java
インターフェースとプログラミング・モデルを提供します。これにより、
mpOpenAPI-1.0 フィーチャーを使用して生成された
API 文書を、ユーザー・フレンドリーなユーザー・インターフェースを使用
するブラウザーで表示できます。
始める前に
OpenAPI V3 仕様および
MicroProfile OpenAPI 1.0 仕様に
ついて学習します。YAML 形式ま
たは JSON 形式の静的 OpenAPI ファイル、MicroProfile OpenAPI アノテーション、または
OpenAPI プログラミング・モデルを使用して、RESTful API をご
使用のアプリケーションで文書化することができます。
トラブルの回避: - extension アノテーションと extensions アノテーションは、操作レベルとクラス・レベルでのみサポ
ートされます。他のエレメントの拡張を指
定するには、他の文書メカニズムを使用します。
- OpenAPI UI は、最初に不正な許可資格情報を入力すると、予期しない動作をします。
後で正しい資格情報を入力しても、その問題は持続し、繰り返し資格情報を
要求するプロンプトが出される場合があります。ページを更新して、正しい資格情報を入力してくだ
さい。
- /openapi エンドポイントまたは
openapi/ui エンドポイントにアクセスする際に、
mpOpenAPI-1.0 が有効になった後に
ssl-1.0 フィーチャーを有効にすると、例外が発生
する可能性があります。この問題を回避するには、両方のフィーチャーを一緒に有効
にします。この問題が発生した後にこれを解決するには、
mpOpenAPI-1.0 フィーチャーを無効にしてから有効にします。
複数のアプリケーションがデプロイされる場合は、OpenAPI 文書を生成するためのアプリ
ケーションを 1 つ選択します。選択されたアプ
リケーションを特定する通知メッセージが出力されます。選択されたアプリケーションが実行中の場合は
、その他のすべてのアプリケーションはアプリケーション・プロセッサーに
よって無視されます。選択されたアプリケーションが停止した後に、次のアプリケーシ
ョンが処理されます。
手順
- オプション: アプリケーションの必要性に応じて、MicroProfile
config メカニズムを使用して MicroProfile OpenAPI 仕様のさまざま
な部分を構成します。 mpOpenAPI-1.0 フィーチャーは、アプリケーション
が開始されると構成された値を読み取ります。
- MicroProfile OpenAPI 仕様から入手可能な、1 つ以上の コア構成をアプリケーション用に構成します。
- 値を追加するには、mpOpenAPI-1.0 フィーチャーは、
アプリケーション用に生成された最終 OpenAPI 文書を、OpenAPI
仕様バージョン 3.0 で宣言された制約と照らし合わせて検証します。エラーと警告の組み合わせ
である検証結果がコンソール・ログに出力されます。
アプリケーションに対する検証は、デフォルト
で有効にされています。以下の構成を設定することで、検証を無効にすることができます。
mp.openapi.extensions.liberty.validation=false
- 文書メカニズムで説明されているように、以下の方法のうち 1 つまたは組み合わせを選択して、
結果の OpenAPI 文書を生成するための入力データを提供します。
- プログラミング・モデルを使用し
て、ブートストラップまたは完全な OpenAPI モデル・ツリーを提供します。
- テキスト・エディターを使用して、YAML 形式または JSON 形式で 静的 OpenAPI 文書を書き込み、
次に、openapi.yaml ファイル、
openapi.yml ファイル、または
openapi.json ファイルを、アプリケーションの META-INF ディレクトリー
に入れます。
- Java コードで MicroProfile OpenAPI アノテーションを指定して、ア
プリケーションを拡張および文書化します。
- 文書メカニズムを使用して OpenAPI モデルをビルド後にアップデートするには、 フィルターを使用します。
- Liberty サーバー構成で mpOpenAPI-1.0 フィーチャーを使用可能にします。
<server>
<featureManager>
<feature>mpOpenAPI-1.0</feature>
</featureManager>
</server>
- アプリケーションをデプロイします。
- オプション: 検証結果を調べて、アプリケーションが OpenAPI 仕様バージョ
ン 3.0 に準拠していることを確認します。
- コンソール・ログを調べ、検証エラーがないか調べます。
- イベントはエラーと警告にグループ化されます。メッセージには生成された文書内の対応する場所
が含まれ、関連するエレメントを識別するのに役立ちます。
サンプル・メッセージ:
CWWKO1650E: Validation of the OpenAPI document produced the following error(s):
- Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/reviewoauth/flows/authorizationCode
- 生成された API 文書をブラウザーで表示します。 以下のいずれかの URL を使用して、生成された API 文書を /openapi エンドポイントで見つけることができます。
- 非 SSL パブリック API の場合は、http://Liberty_host:http_port/openapi で文書を表示します。
- SSL パブリック API の場合は、https://Liberty_host:https_port/openapi で文書を表示します。
タスクの結果
OpenAPI ユーザー・インターフェースは、定義を
/openapi からレンダリングして、
http://Liberty_host:http_port/openapi/ui で UI を
表示します。SSL を有効にする場合、保護された UI に
https://Liberty_host:https_port/openapi/ui でアクセスできます。