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'
以上方法无效。我考虑将 example
从 Widget
模式中移出并移到 #/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
]
}
我有一个带有 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'
以上方法无效。我考虑将 example
从 Widget
模式中移出并移到 #/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
]
}