Swagger使用$ref引用外部YAML schema报无法解析引用错误

你遇到的跨文件$ref解析报错和Schema定义本身无关，核心原因有两个：

1. 如果你是直接通过file://协议在浏览器中打开本地Main.yaml文件，浏览器的同源安全策略会禁止页面加载本地其他路径的文件，Swagger工具拿不到被引用的ThingList.yaml、Thing.yaml内容，就会抛出无明确信息的undefined解析错误。
2. 部分旧版本Swagger UI/Editor默认关闭了相对路径跨文件引用的权限，没有配置允许加载外部本地文件的参数，即使路径写对也会拦截引用请求。

你把所有Schema写到Main.yaml里能正常运行，就是因为单文件模式不需要发起额外的文件加载请求，绕过了上述限制。

根据你的使用场景选对应方案即可：

• 日常维护保留多文件结构，交付/预览时打包为单文件
  用OpenAPI生态的CLI工具做校验和打包，不改变你拆分文件的组织方式，输出的单文件可以直接兼容所有Swagger工具。操作步骤：
  1. 安装Node环境后，执行命令安装打包工具：

     npm install -g @apidevtools/swagger-cli
     

  2. 在Main.yaml所在目录执行校验，确认所有引用路径正确：

     swagger-cli validate Main.yaml
     

  3. 执行打包命令，把多文件引用合并为单文件输出：

     swagger-cli bundle Main.yaml -o bundled-main.yaml -t yaml
     

  后续用生成的bundled-main.yaml在Swagger UI里加载即可，不会出现引用错误。如果要把Schema统一放到object-schemas文件夹，只要修改对应$ref的相对路径，重新执行打包就行，比如Main.yaml里的引用改成./object-schemas/ThingList.yaml#/components/schemas/ThingList，ThingList.yaml里的嵌套引用如果和Thing.yaml同目录，保留原有写法即可。
• 本地直接预览多文件效果
  不要直接双击打开本地YAML文件，在文件根目录启动一个本地静态HTTP服务，绕过浏览器file协议的限制：

  # 安装了Python3的环境下，在YAML文件所在目录执行
  python -m http.server 8080
  

  启动后打开Swagger UI，输入Main.yaml的HTTP地址http://localhost:8080/Main.yaml，所有相对路径的跨文件引用就能正常解析。
• 自行部署Swagger UI的场景
  初始化Swagger UI实例时，把配置项allowRelativeRefs设为true，开启相对路径引用的加载权限即可。

注：你当前贴出的三份YAML文件语法、同目录下的引用路径写法完全符合OpenAPI 3.0规范，不需要修改Schema结构。

内容的提问来源于stack exchange，提问作者Bibily Bob Joe