在Swagger 2.0 Yaml中的多个请求示例

Question

我有一个API，它有一些互斥的参数json有效负载。我想在多个示例中显示此内容，但yaml文件中的schema似乎只能生成一个示例。

如果我的输入可以是:

{
"text": "some text"
}

或

{
"list": ["some text", "some more"]
}

但不

{
"text": "some text",
"list": ["some text", "some more"]
}

如何在swagger 2.0中做到这一点?

像下面这样的模式定义是有误导性的

definitions:
MutexSchema:
type: object
properties:
list:
type: array
items:
type: string
example: ["some text", "some more"]
text:
type: string
example: "Some text"

似乎你不能指定多个body选项。怎样才能很好地显示互斥的有效载荷及其相应的响应?

Answer 1

OpenAPI 2.0不支持互斥属性，但是您可以通过在模式中添加minProperties: 1和maxProperties: 1来模拟这一点。这实际上意味着只有text或list可以传递，但不能同时传递。

definitions:
MutexSchema:
type: object
properties:
list:
type: array
items:
type: string
example: ["some text", "some more"]
text:
type: string
example: "Some text"
minProperties: 1   # <--------
maxProperties: 1

显示互斥有效负载及其相应响应的好方法是什么?

迁移到OpenAPI 3支持oneOf和多个examples的请求和响应。请注意，无法将关联请求和响应示例，但是您可以在description字段中提供额外的信息。

paths:
/something:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MutexSchema'
# Request body examples
examples:
text example:
summary: Example with text
value:
text: Some text
list example:
summary: Example with list
value:
list: [some text, some more]
responses:
'200':
description: OK
content:
application/json:
schema:
...
# Response examples
examples:
ex1:
summary: ...
value:
...
ex2:
summary: ...
value:
...
components:
schemas:
MutexSchema:
oneOf:
- $ref: '#/components/schemas/Text'
- $ref: '#/components/schemas/List'
Text:
type: object
required:
- text     # <--- Property must be marked as required for oneOf to work
properties:
text:
type: string
example: Some text
additionalProperties: false
List:
type: object
required:
- list     # <--- Property must be marked as required for oneOf to work
properties:
list:
type: array
items:
type: string
example: [some text, some more]
additionalProperties: false