如何引用OpenAPI 3中的数组项示例？
如何引用OpenAPI 3中的数组项示例？
提问于 2018-04-15 14:31:14
使用此模式定义：
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)重用霍姆斯示例。但是如果我使用引用的例子：
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
回答 1
Stack Overflow用户
回答已采纳
发布于 2018-04-17 05:05:21
这不是有效的定义：
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，而不是示例的个别部分。这也意味着不可能从多个examples.
构建示例。注意，并非所有元素都支持多个$ref
Swagger UI用户注意： Swagger UI目前支持example (单数)，但不支持examples (复数)。在this issue中跟踪了对examples的支持。
2) Schema Object只支持单数example，不支持复数examples换句话说，模式只支持内联示例。
3)在OpenAPI 3.0中，模式引用使用#/components/schemas/...格式，而不是#/definitions/...格式
我想在两种情况下对
使用相同的示例定义，用户数组和单个用户。
在这种情况下，无法重用示例的一部分。您必须在两个模式中重复该示例值：
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页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接：
https://stackoverflow.com/questions/49839121
复制相关文章
相似问题
腾讯云开发者
