嵌套参考在 Swagger UI / OpenAPI 3 中不起作用

Question

我有这个带有嵌套引用的 OpenAPI 3.0 定义：

Student:
    properties : &BaseStudent
    id:
      type: integer
      format: int64
      description: The ID of the new account.
    name:
      type: string
      description: The human-readable description of this account.
    address:
      $ref : 'address.yaml#/Address'

Address:
    properties : 
     <<* : BaseStudent
    city:
       type: string
      description: City.
    state:
      type: string
      description: State.
    
StudentMarks:
    <<: *BaseStudent
    makr1:
       type: string
      description: Mark1.
    mark2:
      type: string
      description: Mark2.

当我在 Swagger UI 中单击请求选项卡时，它显示错误：

无法解析引用，因为：无法解析指针：/components/schemas/components/schemas/Address 在文档中不存在

实际上，Address 引用应该只是 /components/schemas/。我不知道为什么它指的是/components/schemas/components/schemas/Address。

还有其他方式来指定路径吗？

Answer 1

这个问题可能是由 YAML 锚引起的。

OpenAPI 具有引用定义和进行模型组合的内置方法 - $ref 和 allOf。通常应该使用这些关键字来代替 YAML 锚。

尝试如下重写架构，看看是否能解决问题：

components:
  schemas:

    Student:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: The ID of the new account.
        name:
          type: string
          description: The human-readable description of this account.
        address:
          $ref : 'address.yaml#/Address'

    Address:
      allOf:
        - $ref: '#/components/schemas/BaseStudent'
        - properties:
            city:
              type: string
              description: City.
            state:
              type: string
              description: State.
    
    StudentMarks:
      allOf:
        - $ref: '#/components/schemas/BaseStudent'
        - properties:
            mark1:
              type: string
              description: Mark1.
            mark2:
              type: string
              description: Mark2.