Swagger / OpenAPI 2.0中的Schema对象是否必须具有 type
属性?
一方面,根据JSON Schema Draft 4规范,未指定 type
属性是正常的,这意味着实例可以是任何类型(对象,数组或基元) .
另一方面,我看到很多Swagger模式包含没有 type
属性的Schema对象,但是使用了 properties
属性,这清楚地表明模式作者希望实例成为一个合适的对象(而不是想要接受数组或原语作为有效值) .
所有这些模式都不正确吗?或 type: object
是否存在 type: object
?有's nothing in either the Swagger or the JSON Schema spec that says that is the case. In fact, I'已经看到明确说明不是这样的评论 .
1 回答
就像在JSON Schema中一样,OpenAPI模式对象do not require a type,你是正确的,没有
type
表示any type ."Type-specific"关键字如架构上的
properties
,items
,minLength
等 do not enforce a type . 它以相反的方式工作 - 当针对模式验证实例时,这些关键字仅在实例具有相应类型时应用,否则将被忽略 . 这是JSON Schema Validation规范的相关部分:例如,考虑以下架构:
它是一个有效的模式,即使它结合了特定于对象的关键字
properties
和required
以及特定于字符串的关键字minLength
. 此架构意味着:如果实例是对象,则它必须具有名为
id
的整数属性 . 例如,{"id": 4}
和{"id": -1, "foo": "bar"}
有效,但{}
和{"id": "ACB123"}
不是 .如果实例是字符串,则它必须至少包含8个字符 .
"Hello, world!"
有效,但""
和abc
不是 .其他类型的任何实例都有效 -
true
,false
,-1.234
,[]
,[1, 2, 3]
,[1, "foo", true]
等 .(除了
null
- OpenAPI 2.0没有null
类型,并且不支持null
,扩展属性除外.OpenAPI 3.0支持null
用于nullable: true
的模式 . )如果有工具从其他关键字推断
type
(例如,处理架构没有type
但是properties
总是对象),那么这些工具并不完全遵循OpenAPI规范和JSON架构 .底线:如果架构必须始终是对象,请显式添加
type: object
. 否则您可能会得到意外的结果 .