支持的 JSON Schema 关键字

注意

OAS 3 本指南适用于 OpenAPI 3.0。

OpenAPI 3.0 使用 JSON Schema 规范 Wright Draft 00（又名 Draft 5）的扩展子集来描述数据格式。“扩展子集”意味着支持某些关键字，而不支持某些关键字，某些关键字的用法与 JSON Schema 略有不同，并且引入了其他关键字。

支持的关键字

这些关键字的含义与 JSON Schema 中的相同

• title
• pattern
• required
• enum
• minimum
• maximum
• exclusiveMinimum
• exclusiveMaximum
• multipleOf
• minLength
• maxLength
• minItems
• maxItems
• uniqueItems
• minProperties
• maxProperties

这些关键字支持，但略有不同

• type – 该值必须是单个类型，而不是类型数组。不支持将 null 作为类型，请改用 nullable: true 关键字。
• format – OpenAPI 有其自己的预定义格式，并且还允许自定义格式。
• description – 支持用于富文本表示的 CommonMark 语法。
• items – 如果 type 为 array，则必须存在。项目模式必须是 OpenAPI 模式，而不是标准的 JSON Schema。
• properties – 单个属性定义必须遵循 OpenAPI 模式规则，而不是标准的 JSON Schema。
• additionalProperties – 该值可以是布尔值（true 或 false）或 OpenAPI 模式。
• default – 默认值必须符合指定的模式。
• allOf – 子模式必须是 OpenAPI 模式，而不是标准的 JSON Schema。
• oneOf – 子模式必须是 OpenAPI 模式，而不是标准的 JSON Schema。
• anyOf – 子模式必须是 OpenAPI 模式，而不是标准的 JSON Schema。
• not – 子模式必须是 OpenAPI 模式，而不是标准的 JSON Schema。

不支持的关键字

• $schema
• additionalItems
• const
• contains
• dependencies
• id,
• $id
• patternProperties
• propertyNames

其他关键字

OpenAPI 模式还可以使用以下不属于 JSON Schema 的关键字

• deprecated
• discriminator
• example
• externalDocs
• nullable
• readOnly
• writeOnly
• xml

参考

OpenAPI 3.0 – 模式对象

JSON Schema 验证 – JSON Schema 关键字参考

JSON Schema Draft Wright 00 – 核心 JSON Schema 规范

没有找到您要找的内容？咨询社区
发现错误？请告知我们