使用RouterBuilder配置Vertx OpenApi端点时如何禁用JSON Schema校验

算力阿峰

2026-9-30

Vert.x RouterBuilder 禁用OpenAPI自动JSON校验方案

问题原因

你之前的配置不生效是因为RouterBuilder在调用`createRouter()`生成Router实例时，已经默认给所有匹配OpenAPI规范的operation路由链最前端挂载了默认的ValidationHandler，你之后给Router全局追加的dummy校验handler执行顺序在默认校验之后，请求还没走到你的自定义逻辑就已经被默认校验拦截返回错误了。

解决方案

有两种常用实现方式，按需选择即可：

方式1：仅禁用指定POST接口的校验

针对单个operation调用skipValidation()方法，即可跳过该接口的自动校验挂载，其余接口仍保持默认校验逻辑：

RouterBuilder.create(vertx, pathToMyOpenApi)
      .onSuccess(routerBuilder -> {
        routerBuilder
            .operation("operation")
            .skipValidation() // 关键：跳过当前operation的自动校验挂载
            .handler(BodyHandler.create()) // 禁用校验后需自行添加BodyHandler读取请求体
            .handler(this::operationHandler);

        var router = routerBuilder.createRouter();
        apiRouter.mountSubRouter("/path", router);
});

方式2：全局禁用所有接口的自动校验

如果所有接口都不需要Vert.x的校验逻辑，可以在创建RouterBuilder时通过配置项全局关闭自动校验挂载：

// 配置全局关闭自动挂载校验Handler
OpenAPIRouterOptions routerOptions = new OpenAPIRouterOptions()
        .setMountValidationHandler(false);

RouterBuilder.create(vertx, pathToMyOpenApi, routerOptions)
      .onSuccess(routerBuilder -> {
        routerBuilder
            .operation("operation")
            .handler(BodyHandler.create())
            .handler(this::operationHandler);

        var router = routerBuilder.createRouter();
        apiRouter.mountSubRouter("/path", router);
});