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

Question

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

一方面，根据 JSON 架构草案 4 规范，不指定type属性是可以的，这意味着实例可以是任何类型的(对象、数组或基元)。

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

所有这些架构都不正确吗？还是type: object暗示properties的存在？Swagger 或 JSON 模式规范中没有任何内容表明情况确实如此。事实上，我看到过明确表示事实并非如此的评论。

Answer 1

就像在 JSON 模式中一样，OpenAPI 模式对象不需要type，您是正确的，因为没有type意味着任何类型的。

"特定于类型"的关键字(如properties、items、minLength等)不会在架构上强制使用类型。它的工作方式相反 – 当根据架构验证实例时，这些关键字仅在实例属于相应类型时才适用，否则它们将被忽略。下面是 JSON 架构验证规范的相关部分：

4.1. 关键字和实例基元类型

某些验证关键字仅适用于一个或多个基元类型。当给定关键字无法验证实例的基元类型时，此关键字和实例的验证应成功。

例如，请考虑以下架构：

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.x 中，非类型化模式也允许null值。

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

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