使用npm index.js在Swagger UI中引用多yaml文件实现切换的问题

安全阿岳

2026-10-3

解决Swagger UI多文档切换加载失败问题

核心原因排查

加载失败通常是以下几个问题导致：

完全保留了原来的spec字段，和新增的urls参数同时存在触发配置冲突
用示例中的远程公开接口地址时，触发浏览器跨域限制，Swagger UI无法正常拉取远程yaml/json文件
本地yaml文件直接放在src目录下填写相对路径作为url，webpack/vite等构建工具不会自动处理静态资源导出，导致访问路径404
urls参数没有正确放在SwaggerUI的初始化配置对象内部，导致配置不生效

分步解决方法

1. 处理本地多版本yaml文件

把所有版本的yaml文件放到项目的静态资源目录：

webpack项目：放到public文件夹下，可新建public/swagger-specs/目录，存放v1.yaml、v2.yaml等多版本文件
vite项目：同样放到public目录下，构建时会自动原样导出到根路径

不要放在src目录下用require/import导入，走url加载的文件必须是可通过http路径直接访问的静态资源

2. 调整Swagger UI初始化参数

完全移除spec字段，替换为urls和urls.primaryName配置，本地文件的url直接写静态资源的访问路径即可：

import SwaggerUI from 'swagger-ui'
import 'swagger-ui/dist/swagger-ui.css';

const ui = SwaggerUI({
  // 完全删除原来的spec字段
  dom_id: '#swagger',
  supportedSubmitMethods: [],
  // 新增多文档配置
  urls: [
    {name: "接口版本V1",  url: "/swagger-specs/v1.yaml"},
    {name: "接口版本V2",  url: "/swagger-specs/v2.yaml"},
  ],
  "urls.primaryName": "接口版本V1" // 默认加载的文档名称
});

ui.initOAuth({
  appName: "API NAME",
  clientId: 'implicit'
});

如果需要加载远程文档，需要远程文档的服务端配置CORS跨域规则，允许你的站点访问即可。