Swagger UI / OpenAPI 3 场景下嵌套引用无法正常生效问题

你遇到的路径重复拼接问题是两种错误共同导致的：

1. 引用路径写法不符合OpenAPI 3.0规范
2. 混用YAML原生锚点和OpenAPI的$ref逻辑，触发了Swagger UI的解析异常

具体错误点和修正方法 #

• 如果你当前的Address schema和Student定义在同一个OpenAPI文档的/components/schemas节点下，就不需要加文件名前缀，直接写$ref: '#/components/schemas/Address'即可。你加的address.yaml前缀会被Swagger UI识别为相对路径，和当前解析的上下文路径/components/schemas拼接，就出现了重复的components/schemas前缀。
• 如果你确实要把Address放在独立的address.yaml文件中，要保证外部文件是标准的OpenAPI结构，引用路径需要写全JSON Pointer：$ref: './address.yaml#/components/schemas/Address'，不能直接写#/Address，外部文件的指针必须指向对应组件的完整层级。
• 不推荐用YAML原生锚点做schema复用，不同解析器对锚点的支持程度差异很大，OpenAPI 3.0官方标准的复用方式是用allOf做继承，兼容性最好。
• 你当前的YAML还有语法错误：Address下的<<* : BaseStudent写法错误，缩进也不规范，会先导致YAML结构解析异常，进一步引发后续的引用计算错误。

同文件定义的正确示例 #

openapi: 3.0.3
info:
  title: 示例API
  version: 1.0.0
components:
  schemas:
    # 抽出公共基础 schema
    BaseStudent:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: 账户ID
        name:
          type: string
          description: 账户可读性名称
    Student:
      type: object
      allOf:
        - $ref: '#/components/schemas/BaseStudent'
        - type: object
          properties:
            address:
              $ref: '#/components/schemas/Address'
    Address:
      type: object
      properties:
        city:
          type: string
          description: 城市
        state:
          type: string
          description: 省份
    StudentMarks:
      type: object
      allOf:
        - $ref: '#/components/schemas/BaseStudent'
        - type: object
          properties:
            mark1:
              type: string
              description: 分数1
            mark2:
              type: string
              description: 分数2

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