openapi:引用列表中的现有示例

openapi: referring to an existing example in a list

我有一个带有 Widget 组件的 OpenAPI 3.0.0 规范,其中包括一个 example 部分:

components:
  schemas:
    Widget:
      properties:
        id:
          type: string
        description:
          type: string
        cost:
          type: float
      example:
        id: 1234
        description: An example widget
        cost: 0.10

我正在添加一个 Warehouse 组件,其中包含 Widgets 的列表。有没有办法在 Warehouse 模式中的 Widget 模式上使用 example?类似于:

    Warehouse:
      properties:
        id:
          type: string
        location:
          type: string
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/Widget'
      example:
        id: 4321
        widgets:
          - $ref: '#/components/schemas/Widget'

以上方法无效。我考虑将 exampleWidget 模式中移出并移到 #/components/examples/WidgetExample 中,但我仍然不确定引用它的语法是什么样的。

example关键字不支持$ref.

您可以做的是更改 Warehouse 架构以使用 property-level 示例来表示 widgets 以外的属性,在这种情况下,widgets 的示例将是"inherited" 来自 Widget 架构。至少这是它在 Swagger UI 和 Swagger Editor 中的工作方式。

    Warehouse:
      properties:
        id:
          type: string
          example: 4321   # <----
        location:
          type: string
          example: Sample location   # <----
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/Widget'

Swagger UI 将在请求和响应中为 Warehouse 显示以下示例:

{
  "id": 4321,
  "location": "Sample location",
  "widgets": [
    "id": 1234,
    "description": "An example widget",
    "cost": 0.1
  ]
}