4.15. Eclipse Vert.x OpenAPI の変更点

vertx-web-openapi モジュールは、RouterBuilder を使用して Eclipse Vert.x Web ルーターをビルドします。このルータービルダーは、vertx-web-api-contract モジュールのルータービルダー OpenAPI3RouterFactory と似ています。

vertx-web-openapi モジュールの使用を開始するには、RouterBuilder をインスタンス化します。

RouterBuilder.create(vertx, "petstore.yaml").onComplete(ar -> {
  if (ar.succeeded()) {
    // Spec loaded with success
    RouterBuilder routerBuilder = ar.result();
  } else {
    // Something went wrong during router builder initialization
    Throwable exception = ar.cause();
  }
});

future を使用して RouterBuilder をインスタンス化することもできます。

RouterBuilder.create(vertx, "petstore.yaml")
  .onSuccess(routerBuilder -> {
    // Spec loaded with success
  })
  .onFailure(exception -> {
    // Something went wrong during router builder initialization
  });

ほとんどの場合、古い OpenAPI3RouterFactory メソッドを検索して、新しい RouterBuilder メソッドに置き換えることができます。以下の表は、旧式のメソッドと新しいメソッドの例をいくつか紹介します。

以下の構文を使用して、解析された要求パラメーターにアクセスします。

RequestParameters parameters = routingContext.get(io.vertx.ext.web.validation.ValidationHandler.REQUEST_CONTEXT_KEY);
int aParam = parameters.queryParameter("aParam").getInteger();

Eclipse Vert.x 4 では、RouterFactory.addSecurityHandler() メソッドおよび OpenAPI3RouterFactory.addSecuritySchemaScopeValidator() メソッドは利用できなくなりました。

代わりに RouterBuilder.securityHandler() メソッドを使用します。このメソッドは、io.vertx.ext.web.handler.AuthenticationHandler をハンドラーとして受け入れます。このメソッドは OAuth2Handler を自動的に認識し、セキュリティースキーマを設定します。

新しいセキュリティーハンドラーは、OpenAPI 仕様 で定義された操作も実装します。

vertx-web-openapi モジュールでは、以下の失敗ハンドラーは利用できません。Router.errorHandler(int, Handler) メソッドを使用して失敗ハンドラーを設定する必要があります。

Eclipse Vert.x 4 では、OpenAPI コントラクトは POJO (Plain Old Java Object ) にマッピングされません。そのため、追加の swagger-parser 依存関係は不要になりました。ゲッターおよびリゾルバーを使用して、コントラクトの特定のコンポーネントを取得できます。

以下の例は、1 つの操作を使用して特定のコンポーネントを取得する方法を示しています。

JsonObject model = routerBuilder.operation("getPets").getOperationModel();

以下の例は、完全なコントラクトを取得する方法を示しています。

JsonObject contract = routerBuilder.getOpenAPI().getOpenAPI();

以下の例は、コントラクトの一部を解決する方法を示しています。

JsonObject petModel = routerBuilder.getOpenAPI().getCached(JsonPointer.from("/components/schemas/Pet"));

vertx-web-api-contract モジュールでは、HTTPRequestValidationHandler を使用して HTTP リクエストを検証できます。検証に OpenAPI を使用する必要はありません。

Eclipse Vert.x 4 では、HTTP 要求を検証するため vertx-web-validation モジュールを使用します。このモジュールをインポートし、OpenAPI を使用せずにリクエストを検証できます。ValidationHandler を使用して要求を検証します。

vertx-web-api-service モジュールが更新され、vertx-web-validation モジュールとともに使用できるようになりました。vertx-web-openapi モジュールを使用している場合、Web サービス機能は変更されません。

ただし、OpenAPI を使用しない場合は、vertx-web-validation モジュールで Web サービスモジュールを使用するには、RouteToEBServiceHandler クラスを使用する必要があります。

router.get("/api/transactions")
  .handler(
    ValidationHandlerBuilder.create(schemaParser)
      .queryParameter(optionalParam("from", stringSchema()))
      .queryParameter(optionalParam("to", stringSchema()))
      .build()
  ).handler(
    RouteToEBServiceHandler.build(eventBus, "transactions.myapplication", "getTransactionsList")
  );

vertx-web-api-service モジュールは vertx-web-api-contract をサポートしません。そのため、Eclipse Vert.x 4 にアップグレードする場合は、Eclipse Vert.x OpenAPI アプリケーションを vertx-web-openapi モジュールに移行する必要があります。