Quarkus 3.12.0禁用vertx类路径解析时Swagger UI生产模式失效求解决方案

针对Quarkus 3.12.0中禁用quarkus.vertx.classpath-resolving=false导致Swagger UI返回404的问题，以下是几个无需启用类路径解析（避免写入临时文件）的可行方案：

方案一：手动嵌入Swagger UI静态资源 #

1. 从io.quarkus:quarkus-swagger-ui依赖包中提取所有Swagger UI静态文件（包括index.html、各类js/css/png资源）。
2. 将这些文件复制到项目的src/main/resources/META-INF/resources/swagger-ui目录下。
3. 确保已配置quarkus.swagger-ui.always-include=true，Quarkus默认会从META-INF/resources目录加载静态资源，无需依赖Vert.x的类路径解析特性，即可正常访问Swagger UI。

方案二：自定义Vert.x路由加载类路径资源 #

通过编写自定义路由处理器，手动从类路径读取Swagger UI资源并返回给客户端，绕过Vert.x的类路径解析限制：

import io.vertx.core.http.HttpHeaders;
import io.vertx.ext.web.Router;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Observes;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;

@ApplicationScoped
public class SwaggerUiRouteConfig {

    public void setupSwaggerUiRoutes(@Observes Router router) {
        // 处理Swagger UI首页
        router.get("/swagger-ui/index.html").handler(ctx -> {
            try (InputStream is = getClass().getResourceAsStream("/META-INF/resources/swagger-ui/index.html")) {
                if (is == null) {
                    ctx.response().setStatusCode(404).end();
                    return;
                }
                String content = new String(is.readAllBytes(), StandardCharsets.UTF_8);
                ctx.response()
                        .putHeader(HttpHeaders.CONTENT_TYPE, "text/html;charset=utf-8")
                        .end(content);
            } catch (Exception e) {
                ctx.response().setStatusCode(500).end("加载Swagger UI失败");
            }
        });

        // 处理所有Swagger UI静态资源
        router.get("/swagger-ui/*").handler(ctx -> {
            String resourcePath = ctx.request().path();
            try (InputStream is = getClass().getResourceAsStream("/META-INF/resources" + resourcePath)) {
                if (is == null) {
                    ctx.response().setStatusCode(404).end();
                    return;
                }
                // 根据文件后缀设置响应Content-Type
                String contentType = switch (resourcePath.substring(resourcePath.lastIndexOf('.') + 1)) {
                    case "js" -> "application/javascript";
                    case "css" -> "text/css";
                    case "png" -> "image/png";
                    case "json" -> "application/json";
                    default -> "application/octet-stream";
                };
                ctx.response()
                        .putHeader(HttpHeaders.CONTENT_TYPE, contentType)
                        .end(is.readAllBytes());
            } catch (Exception e) {
                ctx.response().setStatusCode(500).end("加载资源失败");
            }
        });
    }
}

该类会在应用启动时自动注册路由，直接从类路径读取资源，不会触发Vert.x的类路径解析逻辑，也不会写入临时文件。

方案三：使用CDN托管Swagger UI资源（需评估安全风险） #

如果允许加载外部资源，可以修改Swagger UI的index.html，将所有本地资源引用替换为CDN链接（例如jsDelivr或UNPKG）：

• 提取index.html并修改其中的资源路径，比如将./swagger-ui-bundle.js替换为https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14/swagger-ui-bundle.js
• 将修改后的index.html放入src/main/resources/META-INF/resources/swagger-ui目录
• 此方案无需嵌入大量静态资源，但依赖外部CDN，需考虑可用性和安全合规性。

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