如何引用 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 整个示例，而不是示例的各个部分 。这也意味着无法从多个 $ref 构建示例。请注意，并非所有元素都支持复数 examples.

Swagger UI 用户注意事项： Swagger UI 目前支持 example（单数）但不支持 examples（复数） ).在 this issue 中跟踪了对 examples 的支持。

2) Schema Object只支持单数example，不支持复数examples。换句话说，模式仅支持内联示例。

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

I'd like to use the same EXAMPLE definition for Holmes in both cases, the array of users and the single user.

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

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

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

How to reference array item examples in OpenAPI 3?

swagger-ui

openapi