如何在OpenAPI 3中引用数组项目示例？

Question

使用此架构定义：

schemas:
  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      - id: 1
        firstName: Sherlock
        lastName: Holmes
      - id: 2
        firstName: John
        lastName: Watson

我得到了预期的结果：

[
  {
     "id": 1,
     "firstName": "Sherlock",
     "lastName": "Holmes"
  },
  {
     "id": 2,
     "firstName": "John",
     "lastName": "Watson"
  }
]

现在，我想为单个用户（ContactModel1）和用户数组（AllContacts）的一部分重用Holmes示例。但是，如果我使用引用的示例：

schemas:

  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      Homes:
        $ref: '#/components/examples/Homes'
      Watson:
        $ref: '#/components/examples/Watson'

  examples:

    Holmes:
      value:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    Watson:
      value:
        id: 2
        first_name: John
        last_name: Watson

我在Swagger UI中得到了这个意外的结果：

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  },
  {
    "value": {
      "id": 2,
      "first_name": "John",
      "last_name": "Watson",
    },
    "$$ref": "#/components/examples/Watson"
  }
]

和类似的意外示例GET /user/1：

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  }
]

我究竟做错了什么？

我使用此文档作为参考：https :
//swagger.io/docs/specification/adding-examples/#reuse

Answer 1

这不是有效的定义：

components:
  schemas:
    AllContacts:
      type: array
      items:
        $ref: '#/definitions/ContactModel1'
      example:
        Homes:
          $ref: '#/components/examples/Homes'
        Watson:
          $ref: '#/components/examples/Watson'

1）example语法错误。OpenAPI 3.0有两个示例关键字- example（单数）和examples（复数）。它们的工作方式不同：

• example需要内联示例，不支持$ref。
• examples是命名示例的地图（集合）。它支持$ref-但您只能使用$ref整个示例，而不能仅查看示例的各个部分。这也意味着不可能从多个$refs 构建示例。注意并非所有元素都支持复数examples。

Swagger UI用户注意： Swagger UI当前支持example（单数），但不支持examples（复数）。examples在此问题中跟踪对的支持。

2）模式对象仅支持单数，example但不支持复数examples。换句话说，模式仅支持内联示例。

3）在OpenAPI 3.0中，架构引用使用格式#/components/schemas/...，而不是#/definitions/...

我想在两种情况下（用户数组和单个用户）对Holmes使用相同的EXAMPLE定义。

在这种情况下，无法重用示例的一部分。您必须在两个模式中都重复示例值：

components:
  schemas:
    ContactModel1:
      type: object
      properties:
        ...
      example:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    AllContacts:
      type: array
      items:
        $ref: '#/components/schemas/ContactModel1'
      example:
        - id: 1
          first_name: Sherlock
          last_name: Holmes
        - id: 2
          first_name: John
          last_name: Watson