如何用 urls 参数在 Swagger UI 顶部栏加载并切换多个 OpenAPI 规范【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui当你手上有多份 API 定义不同服务、不同版本的 OpenAPI 或 Swagger 规范又不想为每一份规范单独维护一个页面时可以用 Swagger UI 的urls配置参数把它们集中到同一个页面上顶部栏Topbar会列出所有规范的名字点击即可切换当前展示的规范还可以用urls.primaryName指定页面加载后默认展示哪一份。本文覆盖 JavaScript 嵌入方式和 Docker 部署两种方式以及加载结果的验证方法。前提是你已有一份可运行的 Swagger UI 构建产物npm 打包、dist静态资产或官方 Docker 镜像均可参见 安装文档且页面渲染了Topbar组件——官方文档说明使用StandalonePreset时会同时渲染TopBar和ValidatorBadge。urls 的格式与生效条件配置文档中对相关参数的定义如下urlsDocker 变量URLSArray一组 API 定义对象形如[{url: url1, name: name1}, {url: url2, name: name2}]由 Topbar 插件使用。urls.primaryNameDocker 变量URLS_PRIMARY_NAMEString。当取值匹配urls中某个规范的name时Swagger UI 加载后展示该规范而不是默认的urls数组第一项。文档同时给出两条硬性约束配置前需要确认各条目的name和url在数组内必须互相唯一因为它们被用作标识符当urls被使用且 Topbar 插件启用时单独的url参数将不会被解析以urls为准。另外Swagger UI 的配置有三处来源优先级从低到高依次是URL 查询字符串中的键值对 →configUrl指向的外部配置文档 → 传给SwaggerUI({...})的配置对象。urls.primaryName三处都可以设置后文分别给出。在 JavaScript 嵌入页面中配置多规范仓库的 e2e 测试页面 multiple-urls/index.html 就是一个可直接参照的完整示例下面是在其基础上精简后的形态保留影响运行的 presets、plugins 和 layoutdiv idswagger-ui/div script src/swagger-ui-bundle.js charsetUTF-8/script script src/swagger-ui-standalone-preset.js charsetUTF-8/script script window.onload function() { window[SwaggerUIBundle] window[swagger-ui-bundle] window[SwaggerUIStandalonePreset] window[swagger-ui-standalone-preset] const ui SwaggerUIBundle({ urls: [ { name: Petstore OAS, url: /documents/petstore-expanded.openapi.yaml }, { name: Petstore Swagger, url: /documents/petstore.swagger.yaml } ], dom_id: #swagger-ui, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: StandaloneLayout, }) window.ui ui } /script替换说明urls中的name/url条目替换为你自己的规范地址示例值直接取自仓库测试页面指向仓库内 e2e 文档目录下的 Petstore 样例规范swagger-ui.css、swagger-ui-bundle.js、swagger-ui-standalone-preset.js三个资源路径在仓库中由 dev server 提供静态部署时应指向 安装文档所述/dist目录里的同名构建产物dom_id必须与实际div的 id 一致。如果要在加载后默认展示urls中的非第一项在配置对象里加一个带点的平铺键配置文档说明名字中带点的参数是单一字符串不代表嵌套结构SwaggerUIBundle({ urls: [ { name: One, url: /documents/features/urls/1.yaml }, { name: Two, url: /documents/features/urls/2.yaml } ], urls.primaryName: Two, dom_id: #swagger-ui, // 其余 presets / layout 同上 })仓库的测试配置文档 urls-primary-name.yaml 展示了同样的配置在configUrl外部文档中的写法顶层平铺urls:数组和urls.primaryName: Two两行。不写配置、只靠 URL 查询字符串也可以这也是 e2e 测试实际使用的方式/pages/multiple-urls/index.html?urls.primaryNamePetstore Swagger注意取值必须与urls中某个name完全一致。可选分支Docker 部署时用环境变量配置使用官方 Docker 镜像时同样可以改用环境变量。配置文档的 Docker 章节给出数组变量的写法注意按文档要求转义字符URLS[ { url: \https://petstore.swagger.io/v2/swagger.json\, name: \Petstore\ } ]配合 安装文档的镜像运行方式docker pull docker.swagger.io/swaggerapi/swagger-ui docker run -p 80:8080 -e URLS[ { url: \https://petstore.swagger.io/v2/swagger.json\, name: \Petstore\ } ] docker.swagger.io/swaggerapi/swagger-ui默认规范则通过URLS_PRIMARY_NAME设置。docker-compose 的.env文件中文档给出的编码示例是URLS[ { url: https://petstore.swagger.io/v2/swagger.json, name: Petstore } ]验证多规范已加载且可切换页面加载完成后按仓库 e2e 测试 linking-to-configured-urls.cy.js 的判断方式核对顶部栏// 无 urls.primaryName 参数加载 urls 数组第一项 cy.visit(/pages/multiple-urls/index.html) .get(span.url) .contains(/documents/petstore-expanded.openapi.yaml) // 查询参数匹配某个 name渲染对应规范 cy.visit(/pages/multiple-urls/index.html?urls.primaryNamePetstore Swagger) .get(span.url) .contains(/documents/petstore.swagger.yaml)对应的人工验证结论是三条不带urls.primaryName访问时顶部栏当前规范span.url显示的位置是urls数组第一项的 URL带有效?urls.primaryNamename访问时当前规范变为该项的 URL传入不存在的 name测试中为undefinedUrlName时回退到urls第一项而不是报错空白。之后在顶部栏的规范列表中点击另一个名字页面会加载对应规范span.url处显示的 URL 随之变化——这是切换成功的直接证据。限制与注意事项urls各条目的name与url必须唯一冲突的标识会导致切换行为不符合预期启用urls且 Topbar 存在时单独的url参数不再生效不要在两处同时配置规范地址urls依赖 Topbar 组件页面若没有StandalonePreset或等价布局就不会出现顶部栏列表配置对象、configUrl文档、查询字符串三处都设置了urls.primaryName时以优先级高的配置对象为准排障时先确认自己改的是哪一层。【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考