跳过内容

枚举

您可以使用enum关键字来指定请求参数或模型属性的可能值。例如,GET /items?sort=[asc|desc]中的排序参数可以描述为

1
paths:
2
/items:
3
get:
4
parameters:
5
- in: query
6
name: sort
7
description: Sort order
8
schema:
9
type: string
10
enum: [asc, desc]

在 YAML 中,您也可以每行指定一个枚举值

1
enum:
2
- asc
3
- desc

枚举中的所有值都必须符合指定的type。如果您需要为枚举项指定描述,可以在参数或属性的description中进行。

1
parameters:
2
- in: query
3
name: sort
4
schema:
5
type: string
6
enum: [asc, desc]
7
description: >
8
Sort order:
9
* `asc` - Ascending, from A to Z
10
* `desc` - Descending, from Z to A

可为空枚举

可为空枚举可以定义如下

1
type: string
2
nullable: true # <---
3
enum:
4
- asc
5
- desc
6
- null # <--- without quotes, i.e. null not "null"

请注意,null必须明确包含在enum值列表中。此处单独使用nullable: true不足以实现此目的。

可重用枚举

在 OpenAPI 3.0 中,操作参数和数据模型都使用schema,这使得数据类型易于重用。您可以在全局components部分定义可重用枚举,并通过$ref在其他地方引用它们。

1
paths:
2
/products:
3
get:
4
parameters:
5
- in: query
6
name: color
7
required: true
8
schema:
9
$ref: "#/components/schemas/Color"
10
responses:
11
"200":
12
description: OK
13
components:
14
schemas:
15
Color:
16
type: string
17
enum:
18
- black
19
- white
20
- red
21
- green
22
- blue

没有找到您想要的内容?咨询社区
发现错误?告诉我们

© . All rights reserved.