[18.0.0.1 and later]

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

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 つ選択します。選択されたアプ リケーションを特定する通知メッセージが出力されます。選択されたアプリケーションが実行中の場合は 、その他のすべてのアプリケーションはアプリケーション・プロセッサーに よって無視されます。選択されたアプリケーションが停止した後に、次のアプリケーシ ョンが処理されます。

手順

  1. オプション: アプリケーションの必要性に応じて、MicroProfile config メカニズムを使用して MicroProfile OpenAPI 仕様のさまざま な部分を構成します。 mpOpenAPI-1.0 フィーチャーは、アプリケーション が開始されると構成された値を読み取ります。
    • MicroProfile OpenAPI 仕様から入手可能な、1 つ以上の コア構成をアプリケーション用に構成します。
    • 値を追加するには、mpOpenAPI-1.0 フィーチャーは、 アプリケーション用に生成された最終 OpenAPI 文書を、OpenAPI 仕様バージョン 3.0 で宣言された制約と照らし合わせて検証します。エラーと警告の組み合わせ である検証結果がコンソール・ログに出力されます。
      アプリケーションに対する検証は、デフォルト で有効にされています。以下の構成を設定することで、検証を無効にすることができます。
      mp.openapi.extensions.liberty.validation=false
  2. 文書メカニズムで説明されているように、以下の方法のうち 1 つまたは組み合わせを選択して、 結果の OpenAPI 文書を生成するための入力データを提供します。
    • プログラミング・モデルを使用し て、ブートストラップまたは完全な OpenAPI モデル・ツリーを提供します。
    • テキスト・エディターを使用して、YAML 形式または JSON 形式で 静的 OpenAPI 文書を書き込み、 次に、openapi.yaml ファイル、 openapi.yml ファイル、または openapi.json ファイルを、アプリケーションの META-INF ディレクトリー に入れます。
    • Java コードで MicroProfile OpenAPI アノテーションを指定して、ア プリケーションを拡張および文書化します。
    • 文書メカニズムを使用して OpenAPI モデルをビルド後にアップデートするには、 フィルターを使用します。
  3. Liberty サーバー構成で mpOpenAPI-1.0 フィーチャーを使用可能にします。
    <server>
       <featureManager>
          <feature>mpOpenAPI-1.0</feature>
       </featureManager>
    </server>
  4. アプリケーションをデプロイします。
  5. オプション: 検証結果を調べて、アプリケーションが 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
  6. 生成された 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 でアクセスできます。

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

ファイル名: twlp_mpopenapi.html