如何在`map`对象中为属性名编写OpenAPI 3（Swagger）规范？

Question

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

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

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

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

但是这两者都使得在结构上不太明确标识属性是什么，并且使得孩子的ID在隐式而非显式中是唯一的，所以我们想要使用对象或地图。

我已经看过Model with Map/Dictionary Properties的Swagger文档，但这并不适合我的用例。写点如下：

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

产生类似这样的东西：

这充分传达了财产中价值的描述性，但我如何记录＆＃34;密钥＆＃34;的限制。在对象？理想情况下，我想说出类似于＆＃34;它不仅仅是任意字符串，而是与孩子相对应的ID＆＃34;。这有什么支持吗？

Answer 1

你的例子是正确的。

  

如何记录＆＃34;键＆＃34;的限制？在对象？理想情况下，我想说出类似于＆＃34;它不仅仅是任意字符串，而是与孩子相对应的ID＆＃34;。这有什么支持吗？

OpenAPI假设密钥是字符串，但是当前（从OpenAPI 3.0开始）无法限制密钥的内容/格式。您可以在架构description中口头记录任何限制和细节。添加模式示例可以帮助说明字典/地图的外观。

"Parent": {
  "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 ... },
  }

有一个建议在模式中添加support for patternProperties，这将允许定义密钥格式。但是从OpenAPI 3.0.2开始，它还处于提案阶段。

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

// Keys can be: key1, key2, key3

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