如何在“map”对象中编写 OpenAPI 3 (Swagger) 规范的属性名称？

我试图描述的 API 具有一个结构，其中根对象可以包含任意数量的子对象（属性本身就是对象）。根对象中的“键”或属性是子对象的唯一标识符，值是子对象的其余数据。

{
  "child1": { ... bunch of stuff ... },
  "child2": { ... bunch of stuff ... },
  ...
}

这可以类似地建模为数组，例如：

[
  { "id": "child1", ... bunch of stuff ... },
  { "id": "child2", ... bunch of stuff ... },
  ...
]

但这都使得在结构上不太清楚识别属性是什么，并且使子 ID 之间的唯一性变得隐式而不是显式，因此我们想要使用一个对象或一个映射。

我看过 Swagger 文档具有地图/字典属性的模型 https://swagger.io/specification/#model-with-map-dictionary-properties-106，但这并不足以适合我的用例。写一些类似的东西：

"Parent": {
  "additionalProperties": {
    "$ref": "#/components/schemas/Child",
  }

产生这样的结果：

这充分传达了属性中值的描述性，但如何记录对象中“键”的限制？理想情况下，我想说“这不仅仅是任意字符串，它是与孩子相对应的 ID”。这是否以任何方式得到支持？

你的例子是正确的。

如何记录对象中“键”的限制？理想情况下，我想说“这不仅仅是任意字符串，它是与孩子相对应的 ID”。这是否以任何方式得到支持？

开放API 3.1

OAS 3.1 完全支持 JSON Schema 2020-12，包括patternProperties https://json-schema.org/understanding-json-schema/reference/object.html#pattern-properties。此关键字允许您使用正则表达式定义字典键的格式：

"Parent": {
  "type": "object",
  "patternProperties": {
    "^child\d+$": {
      "$ref": "#/components/schemas/Child"
    }
  },
  "description": "A map of `Child` schemas, where the keys are IDs that correspond to the child"
}

或者，如果属性名称是由枚举定义的，您可以使用propertyNames https://json-schema.org/understanding-json-schema/reference/object.html#id4定义该枚举：

"Parent": {
  "type": "object",
  "propertyNames": {
    "enum": ["foo", "bar"]
  },
  "additionalProperties": {
    "$ref": "#/components/schemas/Child"
  }
}

OpenAPI 3.0 和 2.0

字典键被假定为字符串，但无法限制键的内容/格式。您可以在架构中口头记录任何限制和细节description。添加架构示例可以帮助说明您的字典/地图可能是什么样子。

"Parent": {
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/Child"
  },
  "description": "A map of `Child` schemas, where the keys are IDs that correspond to the child",
  "example": {
    "child1": { ... bunch of stuff ... },
    "child2": { ... bunch of stuff ... },
  }

如果可能的键名称已知（例如，它们是枚举的一部分），您可以将字典定义为常规对象，并将键定义为单独的对象属性：

// Keys can be: key1, key2, key3

"Parent": {
   "type": "object",
   "properties": { 
      "key1": { "$ref": "#/components/schemas/Child" },
      "key2": { "$ref": "#/components/schemas/Child" },
      "key3": { "$ref": "#/components/schemas/Child" }
   }
}

然后你可以添加"additionalProperties": false真正确保只使用这些密钥。