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。
RouterBuilder.create(vertx, "petstore.yaml")
.onSuccess(routerBuilder -> {
// Spec loaded with success
})
.onFailure(exception -> {
// Something went wrong during router builder initialization
});
vertx-web-openapi 模块使用 Eclipse Vert.x 文件系统 API 来加载文件。因此，您不必为 classpath 资源指定 /。例如，您可以在应用程序中指定 petstore.yaml。RouterBuilder 可识别您的类路径资源中的合同。
4.15.2. 新的路由器构建器方法
在大多数情况下，您可以使用新的 RouterBuilder 方法搜索和替换旧的 OpenAPI3RouterFactory 方法的使用。下表列出了一些旧方法和新方法示例。
旧的 OpenAPI3RouterFactory 方法 | 新的 RouterBuilder 方法 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
使用以下语法访问解析的请求参数：
RequestParameters parameters = routingContext.get(io.vertx.ext.web.validation.ValidationHandler.REQUEST_CONTEXT_KEY);
int aParam = parameters.queryParameter("aParam").getInteger();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) 方法设置失败处理程序。
| 'vertx-web-api-contract' 模块中的旧方法 | vertx-web-openapi 模块中的新方法 |
|---|---|
|
|
|
|
|
|
4.15.5. 访问 OpenAPI 合同模型
在 Eclipse Vert.x 4 中，OpenAPI 合同没有映射到普通的旧的 Java 对象(POJO)。因此，不再需要额外的 swagger-parser 依赖项。您可以使用 getters 和解析器来检索合同的特定组件。
以下示例演示了如何使用单一操作来检索特定的组件。
JsonObject model = routerBuilder.operation("getPets").getOperationModel();以下示例演示了如何检索完整的合同。
JsonObject contract = routerBuilder.getOpenAPI().getOpenAPI();
以下示例演示了如何解决合同部分。
JsonObject petModel = routerBuilder.getOpenAPI().getCached(JsonPointer.from("/components/schemas/Pet"));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")
);
vertx-web-api-service 模块不支持 vertx-web-api-contract。因此，当您升级到 Eclipse Vert.x 4 时，您必须将 Eclipse Vert.x OpenAPI 应用程序迁移到 vertx-web-openapi 模块。
