首页 文章

Swagger 2.0中没有type属性的Schema对象

提问于
浏览
1

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 回答

  • 1

    就像在JSON Schema中一样,OpenAPI模式对象do not require a type,你是正确的,没有 type 表示any type .

    "Type-specific"关键字如架构上的 propertiesitemsminLengthdo not enforce a type . 它以相反的方式工作 - 当针对模式验证实例时,这些关键字仅在实例具有相应类型时应用,否则将被忽略 . 这是JSON Schema Validation规范的相关部分:

    4.1 . 关键字和实例基元类型某些验证关键字仅适用于一种或多种基本类型 . 当实例的基本类型无法由给定关键字验证时,此关键字和实例的验证应该成功 .

    例如,考虑以下架构:

    definitions:
      Something:
        properties:
          id:
            type: integer
        required: [id]
        minLength: 8
    

    它是一个有效的模式,即使它结合了特定于对象的关键字 propertiesrequired 以及特定于字符串的关键字 minLength . 此架构意味着:

    • 如果实例是对象,则它必须具有名为 id 的整数属性 . 例如, {"id": 4}{"id": -1, "foo": "bar"} 有效,但 {}{"id": "ACB123"} 不是 .

    • 如果实例是字符串,则它必须至少包含8个字符 . "Hello, world!" 有效,但 ""abc 不是 .

    • 其他类型的任何实例都有效 - truefalse-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 . 否则您可能会得到意外的结果 .

相关问题