40

尽管我在OpenAPI 规范中看到了示例：

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

对我来说，为什么使用additionalPropertiesMap/Dictionary 的正确模式并不明显。

规范必须说的唯一具体的事情也无济于事additionalProperties：

以下属性取自 JSON Schema 定义，但它们的定义已根据 Swagger 规范进行了调整。它们的定义与 JSON Schema 的定义相同，只是在原始定义引用 JSON Schema 定义的地方，使用了 Schema Object 定义。

  • 项目
  • 所有的
  • 特性
  • 附加属性
4

2 回答 2

44

陈，我觉得你的回答是对的。

一些可能有帮助的进一步背景：

在 JavaScript 中，这是 JSON 的原始上下文，对象就像字符串到值的哈希映射，其中一些值是数据，另一些是函数。您可以将每个名称-值对视为一个属性。但是 JavaScript 没有类，所以属性名称没有预定义，每个对象都可以有自己独立的一组属性。

JSON Schema 使用properties关键字来验证预先知道的名称-值对；并使用additionalProperties（或者patternProperties，OpenAPI 2.0 不支持）来验证未知的属性。

为了清楚起见：

  • 地图中的属性名称或“键”必须是字符串。它们不能是数字或任何其他值。
  • 正如您所说，属性名称应该是唯一的。不幸的是，JSON 规范并不严格要求唯一性，但建议使用唯一性，这是大多数 JSON 实现所期望的。更多背景在这里。
  • properties并且additionalProperties可以单独使用或组合使用。当 additionalProperties 单独使用时，没有属性，对象本质上用作一个map<string, T>，其中 T 是在 AdditionalProperties 子模式中描述的类型。也许这有助于回答你原来的问题。
  • 在针对单个架构评估对象时，如果属性名称与 中指定的其中之一匹配properties，则其值只需针对为该属性提供的子架构有效。子模式（additionalProperties如果提供）将仅用于验证未包含在properties地图中的属性。
  • additionalProperties在 Swagger 的核心 Java 库中实现的 as 存在一些限制。我在这里记录了这些限制。
于 2016-12-20T12:17:00.653 回答
36

首先，我找到了更好的解释additionalProperties：

对于一个对象，如果给出了 this，那么除了在所有其他属性名称中定义的属性之外，properties所有其他属性名称都是允许的。它们的值都必须与此处给出的模式对象相匹配。如果没有给出，properties则不允许使用除 中定义的属性之外的其他属性。

所以这就是我最终理解的方式：

使用properties，我们可以定义一组类似于Python 的 namedtuple的已知属性，但是如果我们希望拥有更像Python 的 dict或任何其他我们无法指定有多少键或它们是什么的其他哈希/映射，我们应该使用additionalProperties.

additionalProperties将匹配任何属性名称（将充当dict' 键，并且$refortype将是dict' 值的模式，并且由于每个给定对象不应有多个具有相同名称的属性，我们将得到唯一键的强制执行。

请注意，与dict接受任何不可变值作为键的 Python 不同，由于此处的键本质上是属性名称，因此它们必须是字符串。（感谢Ted Epstein的澄清）。pair := string : value这个限制可以追溯到json 规范。

于 2016-12-20T10:27:54.897 回答