如何在"map"对象中编写属性名称的OpenAPI 3(Swagger)规范? [英] How to write OpenAPI 3 (Swagger) specification for property name in `map` object?

问题描述

我要描述的API具有一个结构，其中根对象可以包含任意数量的子对象(本身就是对象的属性).根对象中的键"或属性是子对象的唯一标识符，而值是子对象数据的其余部分.

The API I'm trying to describe has a structure where the root object can contain an arbitrary number of child objects (properties that are themselves objects). The "key", or property in the root object, is the unique identifier of the child object, and the value is the rest of the child object's data.

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

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

This could similarly be modeled as an array, e.g.:

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

但是，这两者在结构上都不清楚标识属性是什么，并使子代ID中的唯一性隐式而不是显式，因此我们想使用对象或地图.

but this both makes it structurally less clear what the identifying property is and makes uniqueness among the children's ID implicit rather than explicit, so we want to use an object, or a map.

我看过带有Map/的模型字典属性，但这并不完全适合我的用例.像这样写:

I've seen the Swagger documentation for Model with Map/Dictionary Properties, but that doesn't adequately suit my use case. Writing something like:

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

产生这样的东西:

这充分传达了属性值的描述性，但是如何记录对象中键"的限制?理想情况下，我想说些类似的话:它不仅是任意字符串，而且是与孩子对应的ID".是否以任何方式支持?

This adequately communicates the descriptiveness of the value in the property, but how do I document what the restrictions are for the "key" in the object? Ideally I'd like to say something like "it's not just any arbitrary string, it's the ID that corresponds to the child". Is this supported in any way?

推荐答案

您的示例是正确的.

如何记录对象中键"的限制?理想情况下，我想说些类似的话:它不仅是任意字符串，而且是与孩子相对应的ID".可以以任何方式支持吗?

how do I document what the restrictions are for the "key" in the object? Ideally I'd like to say something like "it's not just any arbitrary string, it's the ID that corresponds to the child". Is this supported in any way?

OpenAPI 3.1(未来版本，尚未发布)

OAS 3.1将完全支持JSON模式草案2019-09，包括

OpenAPI 3.1 (future version, not yet released)

OAS 3.1 will fully support JSON Schema draft 2019-09, including patternProperties. This keyword lets you to define the format of dictionary keys by using a regular expression:

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

或者如果属性名称由枚举定义，则可以使用

Or if the property names are defined by an enum, you can use propertyNames to define that enum:

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

OpenAPI 3.0和2.0

OpenAPI假定键是字符串，但是(从OpenAPI 3.0开始)目前没有办法限制键的内容/格式.您可以在模式description中口头记录所有限制和详细信息.添加架构示例可以帮助说明您的字典/地图的外观.

OpenAPI 3.0 and 2.0

OpenAPI assumes that the keys are strings, but there's currently (as of OpenAPI 3.0) no way to limit the contents/format of keys. You can document any restrictions and specifics verbally in the schema description. Adding schema examples could help illustrate what your dictionary/map might look like.

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

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

If the possible key names are known (for example, they are part of an enum), you can define your dictionary as a regular object and the keys as individual object properties:

// 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以真正确保仅使用那些键.

Then you can add "additionalProperties": false to really ensure that only those keys are used.

这篇关于如何在"map"对象中编写属性名称的OpenAPI 3(Swagger)规范?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！