为什么 `additionalProperties` 是在 Swagger/OpenAPI 2.0 中表示 Dictionary/Map 的方式 [英] Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

问题描述

虽然我在 OpenAPI 规范中看到了示例:

<块引用>

类型:对象附加属性:$ref: '#/definitions/ComplexModel'

这对我来说并不明显为什么使用 additionalProperties 是 Map/Dictionary 的正确模式.

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

<块引用>

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

• 项目
• 全部
• 属性
• 其他属性

解决方案

陈，我认为你的答案是正确的.

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

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

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

为了清楚起见:

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

Although I have seen the examples in the OpenAPI spec:

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

it isn't obvious to me why the use of additionalProperties is the correct schema for a Map/Dictionary.

It also doesn't help that the only concrete thing that the spec has to say about additionalProperties is:

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

解决方案

Chen, I think your answer is correct.

Some further background that might be helpful:

In JavaScript, which was the original context for JSON, an object is like a hash map of strings to values, where some values are data, others are functions. You can think of each name-value pair as a property. But JavaScript doesn't have classes, so the property names are not predefined, and each object can have its own independent set of properties.

JSON Schema uses the properties keyword to validate name-value pairs that are known in advance; and uses additionalProperties (or patternProperties, not supported in OpenAPI 2.0) to validate properties that are not known.

For clarity:

• The property names, or "keys" in the map, must be strings. They cannot be numbers, or any other value.
• As you said, the property names should be unique. Unfortunately the JSON spec doesn't strictly require uniqueness, but uniqueness is recommended, and expected by most JSON implementations. More background here.
• properties and additionalProperties can be used alone or in combination. When additionalProperties is used alone, without properties, the object essentially functions as a map<string, T> where T is the type described in the additionalProperties sub-schema. Maybe that helps to answer your original question.
• When evaluating an object against a single schema, if a property name matches one of those specified in properties, its value only needs to be valid against the sub-schema provided for that property. The additionalProperties sub-schema, if provided, will only be used to validate properties that are not included in the properties map.
• There are some limitations of additionalProperties as implemented in Swagger's core Java libraries. I've documented these limitations here.

这篇关于为什么 `additionalProperties` 是在 Swagger/OpenAPI 2.0 中表示 Dictionary/Map 的方式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！