dictionary - 为什么 `additionalProperties` 是 Swagger/OpenAPI 2.0 中表示 Dictionary/Map 的方式

Question

虽然我看过OpenAPI spec中的例子:

type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'

对我来说，为什么使用additionalProperties是 map /字典的正确架构并不明显。

规范中有关 additionalProperties 的唯一具体内容是:

The following properties are taken from the JSON Schema definition but their definitions were adjusted to the Swagger Specification. Their definition is the same as the one from JSON Schema, only where the original definition references the JSON Schema definition, the Schema Object definition is used instead.

• items
• allOf
• properties
• additionalProperties

Answer 1

陈，我想your answer是正确的。

一些可能有用的进一步背景:

在 JavaScript(JSON 的原始上下文)中，对象就像字符串到值的 HashMap ，其中某些值是数据，其他值是函数。您可以将每个名称/值对视为一个属性。但 JavaScript 没有类，因此属性名称不是预定义的，每个对象都可以有自己独立的属性集。

JSON 架构使用 properties关键字来验证预先已知的名称-值对；并使用additionalProperties (或 patternProperties ，OpenAPI 2.0 不支持)来验证未知的属性。

为了清楚起见:

• 属性名称或映射中的“键”必须是字符串。它们不能是数字或任何其他值。
• 正如您所说，属性名称​​应该是唯一的。不幸的是，JSON 规范并不严格要求唯一性，但建议唯一性，并且大多数 JSON 实现都期望唯一性。更多背景here .
• properties和additionalProperties可单独或组合使用。当additionalProperties单独使用而不带属性时，该对象本质上充当map<string, T>其中 T 是additionalProperties 子模式中描述的类型。也许这有助于回答您原来的问题。
• 根据单个架构评估对象时，如果属性名称与 properties 中指定的名称之一匹配， ，其值只需针对为该属性提供的子模式有效。 additionalProperties子架构(如果提供)将仅用于验证 properties 中未包含的属性。 map 。
• additionalProperties 有一些限制在 Swagger 的核心 Java 库中实现。我已经记录了这些限制 here .