如何为Swagger-UI Webjar添加配置以支持查询参数传入自定义URL

该需求可实现，无需修改Swagger-UI Webjar本身的源码。
核心原因是Swagger UI 3.x及以上版本默认将queryConfigEnabled初始化参数设为false，关闭了通过查询参数读取自定义配置的能力，Webjar形式部署的配置逻辑和独立部署版完全对齐，只要在初始化阶段打开该配置项即可生效。

以下是通用落地方式，适配绝大多数以Webjar形式托管Swagger UI的服务端框架（Spring Boot/Spring MVC、Quarkus、普通Servlet容器等均适用）：

• 版本校验
  先确认当前引入的Swagger-UI Webjar版本不低于3.0.0，建议升级到3.52.0以上的稳定版本，避免低版本配置项不兼容问题。
• 配置注入（两种方式二选一即可）
  • 方式一：自定义Swagger入口页（无侵入、最稳定）
    不要直接使用Webjar自带的默认index.html，在你项目自身的静态资源目录下新建Swagger入口页面，引入Webjar内的Swagger UI静态资源后，在初始化代码中开启查询参数配置能力，示例代码如下：

    <!DOCTYPE html>
    <html lang="zh-CN">
    <head>
      <meta charset="UTF-8">
      <title>API文档</title>
      <link rel="stylesheet" href="/webjars/swagger-ui/swagger-ui.css" >
    </head>
    <body>
    <div id="swagger-ui"></div>
    <script src="/webjars/swagger-ui/swagger-ui-bundle.js"></script>
    <script src="/webjars/swagger-ui/swagger-ui-standalone-preset.js"></script>
    <script>
      window.onload = function() {
        window.ui = SwaggerUIBundle({
          // 替换为你服务默认的OpenAPI文档地址
          url: "/v3/api-docs",
          dom_id: '#swagger-ui',
          deepLinking: true,
          presets: [
            SwaggerUIBundle.presets.apis,
            SwaggerUIStandalonePreset
          ],
          layout: "StandaloneLayout",
          // 核心配置：开启查询参数传入自定义配置的能力
          queryConfigEnabled: true
        })
      }
    </script>
    </body>
    </html>
    

    最后将项目中原先指向Webjar默认Swagger页面的路由，改为指向你新建的这个自定义页面即可。
  • 方式二：覆盖Webjar默认初始化脚本
    静态资源托管框架普遍遵循「项目自有静态资源优先级高于Webjar内同名资源」的规则，你可以找到对应版本Webjar内的swagger-initializer.js初始化脚本（路径一般为/META-INF/resources/webjars/swagger-ui/<版本号>/swagger-initializer.js），复制到你项目的静态资源对应路径下，在初始化配置对象中加入queryConfigEnabled: true配置项即可。这种方式不需要修改原有Swagger页面的访问路径，对现有接入逻辑改动最小，重启服务后就会自动加载你修改后的初始化逻辑，无需改动Webjar依赖包本身。
• 效果验证
  配置生效后，就可以通过查询参数url传入自定义OpenAPI地址实现动态切换，例如访问/swagger-ui.html?url=https://example.com/your-custom-openapi.yaml即可加载对应地址的API文档。

• 如果你的服务配置了静态资源访问拦截规则，需要将自定义页面/覆盖的初始化脚本路径加入访问白名单，避免出现404问题。
• 若需要对传入的自定义URL做安全校验，可以在前端页面对url参数做合法性判断后再传入Swagger UI初始化逻辑，避免加载未授权的第三方文档。

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