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/...

我想在两种情况下都使用与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

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

1 个答案: