Question

我有一个带有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的列表。有没有办法在example模式的Widget模式上使用Warehouse？像这样：

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

以上操作无效。我曾考虑将example从Widget模式中移出，移到#/components/examples/WidgetExample中，但是我仍然不确定要引用什么语法。

Answer 1

example关键字不支持$ref。

您可以做的是更改Warehouse模式，对除widgets以外的属性使用属性级别的示例，在这种情况下，widgets的示例将从“继承” Widget模式。至少这是它在Swagger UI和Swagger编辑器中的工作方式。

    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
  ]
}

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

1 个答案: