如何在Vert.X应用中开启Swagger-UI并展示接口路由

我来一步步帮你搞定Vert.x集成Swagger-UI的事儿，你已经有了手动编辑好的Swagger JSON配置，接下来按下面的步骤操作就行：

1. 添加必要的依赖 #

首先得在项目里引入Vert.x Swagger相关的依赖，根据你用的构建工具选择对应的配置：

Maven（pom.xml） #

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-core</artifactId>
    <version>2.2.15</version>
</dependency>
<dependency>
    <groupId>com.github.phiz71</groupId>
    <artifactId>vertx-swagger</artifactId>
    <version>1.6.0</version>
</dependency>

Gradle（build.gradle） #

implementation 'io.swagger:swagger-core:2.2.15'
implementation 'com.github.phiz71:vertx-swagger:1.6.0'

2. 确认Swagger JSON文件位置 #

你已经把swagger-editor导出的JSON放到src/main/resources目录了，建议给它起个好记的名字（比如swagger.json），确保文件路径正确，后续代码会直接读取这个文件。

3. 在Vert.x应用中配置Swagger路由 #

接下来要在你的Vert.x启动类里添加Swagger相关的路由配置，把Swagger-UI的静态资源和API文档接口暴露出来：

import io.vertx.core.Vertx;
import io.vertx.core.http.HttpServer;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.StaticHandler;
import com.github.phiz71.vertx.swagger.SwaggerRouter;
import io.swagger.models.Swagger;
import io.swagger.parser.SwaggerParser;
import io.vertx.core.AbstractVerticle;

public class MainVerticle extends AbstractVerticle {

    @Override
    public void start() throws Exception {
        Vertx vertx = Vertx.vertx();
        Router router = Router.router(vertx);

        // 加载resources目录下的Swagger JSON配置
        Swagger swagger = new SwaggerParser().read("swagger.json");

        // 配置API文档的访问路由，前端UI会通过这个接口获取配置
        SwaggerRouter.swaggerRouter(router, swagger, "/api-docs");

        // 配置Swagger-UI的静态资源访问
        // 注意这里的路径要和你引入的swagger-ui webjar版本对应，示例用的是4.15.5版本
        router.route("/swagger-ui/*").handler(StaticHandler.create("META-INF/resources/webjars/swagger-ui/4.15.5/")
                .setCachingEnabled(false));

        // 把你之前定义的业务接口路由添加到router中
        // 比如：router.get("/api/users").handler(this::getUserListHandler);

        // 启动HTTP服务器
        HttpServer server = vertx.createHttpServer();
        server.requestHandler(router).listen(8080, res -> {
            if (res.succeeded()) {
                System.out.println("Vert.x服务启动成功，端口：8080");
                System.out.println("Swagger-UI访问地址：http://localhost:8080/swagger-ui/index.html?url=/api-docs");
            } else {
                System.err.println("服务启动失败：" + res.cause());
            }
        });
    }
}

这里有几个关键细节要注意：

• StaticHandler里的路径要和你引入的swagger-ui webjar版本匹配，如果你用了不同版本，记得修改路径里的版本号
• 访问Swagger-UI时需要通过url参数指定API文档的接口地址（也就是我们配置的/api-docs），这样UI才能正确加载你的接口配置

4. 验证效果 #

启动你的Vert.x应用，然后在浏览器里访问http://localhost:8080/swagger-ui/index.html?url=/api-docs，就能看到和SpringBoot中类似的Swagger-UI界面了，里面会展示你在swagger-editor里编辑的所有接口路由，还可以直接在UI里测试接口。

额外提示 #

• 如果后续修改了Swagger JSON配置，只需要替换src/main/resources下的文件，重启应用就能生效
• 要是想让Swagger-UI默认加载你的API文档，可以自定义Swagger-UI的index.html，不过直接带url参数的方式已经足够方便
• 确保你的业务接口路由和Swagger JSON里定义的路径、请求方式完全一致，这样UI里才能正确关联接口并正常测试

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