Vertx 4.3.4(RX Java)中基于OpenAPIv3 YAML实现路由与输入验证

问题场景 #

使用Vert.x 4.3.4配合RxJava2，期望通过OpenAPIv3.yaml初始化路由，并对YAML中声明的路由及输入模型做用户输入验证。已实现基础路由代码，尝试添加ValidationHandler时，找不到SchemaParser的正确创建方式，且4.3.4版本相关废弃API无官方示例。当前仅持有OpenAPIv3.yaml文件，依赖仅包含vertx-rx-java2。

现有路由代码 #

router.get("/configs").handler(this.handlers.configHandler::getAll);

待添加的验证逻辑 #

.handler(
  ValidationHandlerBuilder
    .create(schemaParser)
    .build()
);

解决方案 #

第一步：补充必要依赖 #

vertx-rx-java2不包含OpenAPI契约解析和JSON Schema验证的模块，需添加以下依赖：

<!-- OpenAPI 3 契约解析依赖 -->
<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web-api-contract</artifactId>
    <version>4.3.4</version>
</dependency>
<!-- JSON Schema 解析器依赖 -->
<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-json-schema</artifactId>
    <version>4.3.4</version>
</dependency>
<!-- RxJava2 风格的OpenAPI契约绑定（可选，若需要Rx链式调用） -->
<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web-api-contract-rx-java2</artifactId>
    <version>4.3.4</version>
</dependency>

第二步：加载OpenAPI规范并创建SchemaParser #

通过SchemaParserFactory创建兼容OpenAPIv3格式的解析器，再结合加载的OpenAPI契约生成对应路由的ValidationHandler。

RxJava2风格实现代码

// 加载OpenAPIv3 YAML文件（Rx链式调用）
vertx.fileSystem().rxReadFile("openapi-v3.yaml")
    .map(openApiBuffer -> OpenAPIContract.from(openApiBuffer))
    .subscribe(contract -> {
        // 创建兼容OpenAPIv3的SchemaParser
        SchemaParser schemaParser = SchemaParserFactory.getParser(SchemaParserFactory.Format.OpenAPI3);
        
        // 从契约中获取目标路由的操作定义（路径+HTTP方法需与YAML中完全一致）
        Operation configGetOperation = contract.getOperation("/configs", HttpMethod.GET);
        
        // 构建ValidationHandler并绑定到路由
        ValidationHandler validationHandler = ValidationHandlerBuilder.create(schemaParser)
            .operation(configGetOperation) // 绑定对应操作的验证规则
            .build();
            
        router.get("/configs")
            .handler(validationHandler) // 先执行验证
            .handler(this.handlers.configHandler::getAll); // 验证通过后执行业务逻辑
    }, throwable -> {
        // 处理文件加载或解析异常
        throwable.printStackTrace();
    });

关键注意点 #

• 必须将ValidationHandler放在业务Handler之前，确保先验证再执行业务逻辑
• 路由的路径、HTTP方法必须与OpenAPIv3.yaml中定义的完全匹配，否则无法获取对应的Operation规则
• SchemaParserFactory.Format.OpenAPI3专门用于适配OpenAPIv3的Schema格式，不能用普通的JSON Schema解析器替代

内容的提问来源于stack exchange，提问作者user20405467