嵌套引用在 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

实际上，< code >地址引用应该仅是< code >/components/schemas/。我不确定它为什么引用< code >/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.