OpenAPI(Swagger)中的枚举和示例之间有什么区别



在OpenAPI中,示例枚举都可以用type: string定义,例如:

type: string
example:
- FOOD
- WATER
type: string
enum:
- FOOD
- WATER

使用上述任何一种结构进行验证有什么不同?以上内容可以互换使用吗?

enumexample具有不同的含义,用于不同的目的。

enum为实例指定可能值(换句话说,它限制可能值(。它类似于C#、Java和其他编程语言中的枚举。例如,enum: [FOOD, WATER]意味着该值可以是"FOOD""WATER",而不是其他值。

example指定一个示例值用于文档或其他目的(但不用于验证(。比方说,如果您拥有具有username属性的User架构,则可以指定demoUser作为示例用户名。但是example值并不是属性的唯一可能值,它可以有其他值。

User:
type: object
property:
username:
type: string
example: demoUser

模式可以同时具有enumexample:

type: string
enum:
- FOOD
- WATER
example: WATER


enum不同,example不影响验证。但是,像代码生成器和文档生成器这样的工具可能期望example值与它们的模式匹配。这样的工具会将问题中的示例标记为无效,因为模式被定义为string,但示例值是一个数组(即不同的数据类型(。

type: string
# Incorrect
example:
- FOOD
- WATER
# Correct
example: FOOD

最新更新