枚举
您可以使用enum
关键字来指定请求参数或模型属性的可能值。例如,GET /items?sort=[asc|desc]
中的排序参数可以描述为
1paths:2 /items:3 get:4 parameters:5 - in: query6 name: sort7 description: Sort order8 schema:9 type: string10 enum: [asc, desc]
在 YAML 中,您也可以每行指定一个枚举值
1enum:2 - asc3 - desc
枚举中的所有值都必须符合指定的type
。如果您需要为枚举项指定描述,可以在参数或属性的description
中进行。
1parameters:2 - in: query3 name: sort4 schema:5 type: string6 enum: [asc, desc]7 description: >8 Sort order:9 * `asc` - Ascending, from A to Z10 * `desc` - Descending, from Z to A
可为空枚举
可为空枚举可以定义如下
1type: string2nullable: true # <---3enum:4 - asc5 - desc6 - null # <--- without quotes, i.e. null not "null"
请注意,null
必须明确包含在enum
值列表中。此处单独使用nullable: true
不足以实现此目的。
可重用枚举
在 OpenAPI 3.0 中,操作参数和数据模型都使用schema
,这使得数据类型易于重用。您可以在全局components
部分定义可重用枚举,并通过$ref
在其他地方引用它们。
1paths:2 /products:3 get:4 parameters:5 - in: query6 name: color7 required: true8 schema:9 $ref: "#/components/schemas/Color"10 responses:11 "200":12 description: OK13components:14 schemas:15 Color:16 type: string17 enum:18 - black19 - white20 - red21 - green22 - blue