在OpenAPI中,示例和枚举都可以用type: string
定义,例如:
type: string
example:
- FOOD
- WATER
type: string
enum:
- FOOD
- WATER
使用上述任何一种结构进行验证有什么不同?以上内容可以互换使用吗?
enum
和example
具有不同的含义,用于不同的目的。
enum
为实例指定可能值(换句话说,它限制可能值(。它类似于C#、Java和其他编程语言中的枚举。例如,enum: [FOOD, WATER]
意味着该值可以是"FOOD"
或"WATER"
,而不是其他值。
example
指定一个示例值用于文档或其他目的(但不用于验证(。比方说,如果您拥有具有username
属性的User
架构,则可以指定demoUser作为示例用户名。但是example
值并不是属性的唯一可能值,它可以有其他值。
User:
type: object
property:
username:
type: string
example: demoUser
模式可以同时具有enum
和example
:
type: string
enum:
- FOOD
- WATER
example: WATER
与enum
不同,example
不影响验证。但是,像代码生成器和文档生成器这样的工具可能期望example
值与它们的模式匹配。这样的工具会将问题中的示例标记为无效,因为模式被定义为string
,但示例值是一个数组(即不同的数据类型(。
type: string
# Incorrect
example:
- FOOD
- WATER
# Correct
example: FOOD