如何在 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（复数）。在this issue 中跟踪对examples 的支持。

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

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

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

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

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