如何为'map'对象中的属性名编写OpenAPI3(Swagger)规范？

Question

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

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

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

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

但这既使得识别属性在结构上不那么清楚，又使得子ID之间的唯一性是隐式的，而不是显式的，所以我们想使用一个对象或一个映射。

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

Answer 1

你的例子是正确的。

如何记录对象中“键”的限制？理想情况下，我想说“它不是任意的字符串，而是与子字符串相对应的ID”。这有任何支持吗？

OAS3.1完全支持JSON模式2020-12，包括patternproperties。此关键字允许您使用正则表达式定义字典键的格式：

"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"
}

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

"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" }
   }
}