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

问题描述

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

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.

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

Yields something like this:

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?

解决方案

Your example is correct.

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 fully supports JSON Schema 2020-12, including patternProperties. This keyword lets you define the format of dictionary keys by using a regular expression:

"Parent": {
  "type": "object",
  "patternProperties": {
    "^childd+$": {
      "$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 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" }
   }
}

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

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