如何创建含$ref引用子文件的OpenAPI 3.0.1规范文件？

我没法让OpenAPI 3.0.1的Swagger外部引用生效，渲染时直接抛异常。因为Azure SDK架构限制，没有自动生成器，必须拆分大Swagger文档来提升可维护性。

我尝试的代码如下：

paths:
  /v1:
    $ref: 'first-api.yaml#/paths/~1v1'
  /v2:
    $ref: 'second-api.yaml#/paths/~1v2'

Stack Overflow上的相关解决方案都不管用，IntelliJ IDEA的OpenAI (Swagger) Editor插件还报错（错误截图显示引用解析失败）。我在在线工具上的测试也失败了。

可直接运行的示例项目 #

本地文件结构 #

├── main.yaml
└── paths/
    ├── first-api.yaml
    └── second-api.yaml

main.yaml（主文档） #

openapi: 3.0.1
info:
  title: 拆分式API示例
  version: 1.0.0
paths:
  /v1:
    $ref: './paths/first-api.yaml#/paths/~1v1'
  /v2:
    $ref: './paths/second-api.yaml#/paths/~1v2'

paths/first-api.yaml（子文档1） #

paths:
  /v1:
    get:
      summary: 获取v1版本数据
      responses:
        '200':
          description: 成功返回数据
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    example: "这是v1接口的响应"

paths/second-api.yaml（子文档2） #

paths:
  /v2:
    get:
      summary: 获取v2版本数据
      responses:
        '200':
          description: 成功返回数据
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    example: "这是v2接口的响应"

关键注意事项 #

• 引用路径要和实际文件存储层级匹配，比如子文档在paths文件夹下，就得写./paths/xxx.yaml，别写错路径
• 引用片段里的~1是/的URL编码，所以#/paths/~1v1正好对应子文档里的paths:/v1，语法不能错
• 部分IDE插件或在线工具对外部引用支持有限，本地测试优先用Swagger UI的本地部署版本，能正常解析相对路径引用
• 如果用在线工具测试，要确保所有子文档都能被公开访问，引用路径需使用完整的可访问URL

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