swagger - Swagger 2.0 中没有类型属性的架构对象

Question

Swagger/OpenAPI 2.0 中的 Schema 对象是否必须具有 type属性与否？

一方面，根据 JSON Schema Draft 4 规范，没有指定 type属性是可以的，意味着实例可以是任何类型(对象、数组或基元)。

另一方面，我见过很多包含 Schema 对象而没有 type 的 Swagger 模式。属性，但带有 properties属性，这清楚地表明模式作者希望实例是一个适当的对象(并且不想接受数组或原始值作为有效值)。

所有这些模式都不正确吗？或者是 type: object properties 的存在暗示? Swagger 或 JSON Schema 规范中都没有说明情况就是如此。事实上，我看到一些评论明确表示情况并非如此。

Answer 1

就像在 JSON Schema 中一样，OpenAPI 模式对象 do not require a type ，你是对的，没有 type意味着 any type .

“特定于类型”的关键字，例如 properties , items , minLength等不强制类型 在架构上。反之亦然——当根据模式验证实例时，这些关键字仅在实例具有相应类型时才适用，否则它们将被忽略。这是JSON Schema Validation的相关部分规范:

4.1. Keywords and instance primitive types

Some validation keywords only apply to one or more primitive types. When the primitive type of the instance cannot be validated by a given keyword, validation for this keyword and instance SHOULD succeed.

例如，考虑这个模式:

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

这是一个有效的模式，即使它结合了特定于对象的关键字 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]等。在 OpenAPI 3.0 中，无类型模式也 allow null values .

如果有工具可以推断 type从其他关键字(例如，处理没有 type 但使用 properties 作为始终对象的模式)，那么这些工具并不完全遵循 OpenAPI 规范和 JSON 模式。

底线:如果架构必须始终是对象，请添加 type: object明确地。否则你可能会得到意想不到的结果。