4.15. Eclipse Vert.x OpenAPI 的更改

在 Eclipse Vert.x 4 中，有新的模块 vertx-web-openapi 可用。仅用 vertx-web 使用此模块来开发合同驱动的应用程序。

新模块非常适合 Eclipse Vert.x Web Router。新模块需要以下 Eclipse Vert.x 依赖项：

vertx-json-schema
vertx-web-validation

新模块位于软件包 io.vertx.ext.web.openapi 中。

在 Eclipse Vert.x 4 中，支持旧的 OpenAPI 模块 vertx-web-api-contract，以促进迁移到新模块。建议您移至新模块 vertx-web-openapi 来使用新功能。

4.15.1. 新模块使用路由器构建程序
复制链接

vertx-web-openapi 模块使用 RouterBuilder 来构建 Eclipse Vert.x Web 路由器。此路由器构建器与 vertx-web-api-contract 模块中的路由器 builer 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();
  }
});

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();
  }
});

Copy to Clipboard

Toggle word wrap

您还可以使用未来实例化 RouterBuilder。

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

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

Copy to Clipboard

Toggle word wrap

注意

vertx-web-openapi 模块使用 Eclipse Vert.x 文件系统 API 来加载文件。因此，您不必为 classpath 资源指定 /。例如，您可以在应用程序中指定 petstore.yaml。RouterBuilder 可识别您的类路径资源中的合同。

4.15.2. 新的路由器构建器方法
复制链接

在大多数情况下，您可以使用新的 RouterBuilder 方法搜索和替换旧的 OpenAPI3RouterFactory 方法的使用。下表列出了一些旧方法和新方法示例。

Expand

旧的 `OpenAPI3RouterFactory` 方法	新的 `RouterBuilder` 方法
`routerFactory.addHandlerByOperationId("getPets", handler)`	`routerBuilder.operation("getPets").handler(handler)`
`routerFactory.addFailureHandlerByOperationId("getPets", handler)`	`routerBuilder.operation("getPets").failureHandler(handler)`
`routerFactory.mountOperationToEventBus("getPets", "getpets.myapplication")`	`routerBuilder.operation("getPets").routeToEventBus("getpets.myapplication")`
`routerFactory.addGlobalHandler(handler)`	`routerBuilder.rootHandler(handler)`
`routerFactory.addBodyHandler(handler)`	`routerBuilder.bodyHandler(handler)`
`routerFactory.getRouter()`	`routerBuilder.createRouter()`

使用以下语法访问解析的请求参数：

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

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

Copy to Clipboard

Toggle word wrap

4.15.3. 处理安全性
复制链接

在 Eclipse Vert.x 4 中，方法 RouterFactory.addSecurityHandler （） 和 OpenAPI3RouterFactory.addSecuritySchemaScopeValidator （） 不再可用。

改为使用 RouterBuilder.securityHandler （） 方法。此方法接受 io.vertx.ext.web.handler.AuthenticationHandler 作为处理程序。该方法自动识别 OAuth2Handler 并设置安全架构。

新的安全处理程序也实现了 OpenAPI 规格中定义的操作。

4.15.4. 处理常见故障
复制链接

在 vertx-web-openapi 模块中，以下失败处理程序不可用：您必须使用 Router.errorHandler (int, Handler) 方法设置失败处理程序。

Expand

'vertx-web-api-contract' 模块中的旧方法	`vertx-web-openapi` 模块中的新方法
`routerFactory.setValidationFailureHandler(handler)`	`router.errorHandler (400、处理程序)`
`routerBuilder.setNotImplementedFailureHandler(handler)`	`router.errorHandler (501、处理程序)`

4.15.5. 访问 OpenAPI 合同模型
复制链接

在 Eclipse Vert.x 4 中，OpenAPI 合同没有映射到普通的旧的 Java 对象(POJO)。因此，不再需要额外的 swagger-parser 依赖项。您可以使用 getters 和解析器来检索合同的特定组件。

以下示例演示了如何使用单一操作来检索特定的组件。

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

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

Copy to Clipboard

Toggle word wrap

以下示例演示了如何检索完整的合同。

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

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

Copy to Clipboard

Toggle word wrap

以下示例演示了如何解决合同部分。

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

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

Copy to Clipboard

Toggle word wrap

4.15.6. 在没有 OpenAPI 的情况下验证 Web 请求
复制链接

在 vertx-web-api-contract 模块中，您可以使用 HTTPRequestValidationHandler 验证 HTTP 请求。您不必使用 OpenAPI 进行验证。

在 Eclipse Vert.x 4 中，验证 HTTP 请求使用 vertx-web-validation 模块。您可以导入这个模块，并在不使用 OpenAPI 的情况下验证请求。使用 ValidationHandler 验证请求。

4.15.7. Eclipse Vert.x web API 服务中的更新
复制链接

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")
  );

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

Copy to Clipboard

Toggle word wrap

vertx-web-api-service 模块不支持 vertx-web-api-contract。因此，当您升级到 Eclipse Vert.x 4 时，您必须将 Eclipse Vert.x OpenAPI 应用程序迁移到 vertx-web-openapi 模块。

返回顶部

4.15. Eclipse Vert.x OpenAPI 的更改

4.15.1. 新模块使用路由器构建程序
复制链接

4.15.2. 新的路由器构建器方法
复制链接

4.15.3. 处理安全性
复制链接

4.15.4. 处理常见故障
复制链接

4.15.5. 访问 OpenAPI 合同模型
复制链接

4.15.6. 在没有 OpenAPI 的情况下验证 Web 请求
复制链接

4.15.7. Eclipse Vert.x web API 服务中的更新
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

4.15. Eclipse Vert.x OpenAPI 的更改

4.15.1. 新模块使用路由器构建程序复制链接链接已复制到粘贴板!

4.15.2. 新的路由器构建器方法复制链接链接已复制到粘贴板!

4.15.3. 处理安全性复制链接链接已复制到粘贴板!

4.15.4. 处理常见故障复制链接链接已复制到粘贴板!

4.15.5. 访问 OpenAPI 合同模型复制链接链接已复制到粘贴板!

4.15.6. 在没有 OpenAPI 的情况下验证 Web 请求复制链接链接已复制到粘贴板!

4.15.7. Eclipse Vert.x web API 服务中的更新复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

4.15.1. 新模块使用路由器构建程序
复制链接

4.15.2. 新的路由器构建器方法
复制链接

4.15.3. 处理安全性
复制链接

4.15.4. 处理常见故障
复制链接

4.15.5. 访问 OpenAPI 合同模型
复制链接

4.15.6. 在没有 OpenAPI 的情况下验证 Web 请求
复制链接

4.15.7. Eclipse Vert.x web API 服务中的更新
复制链接