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

问题描述

虽然我已经看到了 OpenAPI 规范中的示例:

类型:对象附加属性:$ref: '#/定义/复杂模型'

我不清楚为什么使用 additionalProperties 是地图/字典的正确模式.

规范中关于 additionalProperties 的唯一具体内容也无济于事:

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

• 项目
• 全部
• 属性
• 附加属性

解决方案

Chen，我认为您的回答是正确的.

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

在 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:

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:

解决方案

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 的方式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！