摇摆：

Question

例：

{
    "a_property": {
        "foo": {
            "property_1": "a string 1",
            "property_2": "a string 2"
        },
        "bar": {
            "property_1": "a string 3",
            "property_2": "a string 4"
        }
    }
}

“foo”和“bar”可以是任何字符串键，但它们在键集中应该是唯一的。

我知道，使用Swagger，我可以定义一个对象数组，但这给出了一个不同的API，因为那时我们将拥有如下内容：

{
    "a_property": [
        {
            "key": "foo"
            "property_1": "a string 1",
            "property_2": "a string 2"
        },
        {
            "key": "bar"
            "property_1": "a string 3",
            "property_2": "a string 4"
        }
    ]
}

我已经阅读了“开放API规范”-“添加地图数据类型支持#38”页面。据我了解，它推荐使用additionalProperties，但似乎并没有回答我的需求(或者说与我使用的Swagger UI 2.1.4不兼容)。我错过了什么吗？

到目前为止，我已经找到了以下解决方法(在Swagger JSON中):

a_property: {
    description: "This is a map that can contain several objects indexed by different keys.",
    type: object,
    properties: {
        key: {
            description: "map item",
            type: "object",
            properties: {
                property_1: {
                    description: "first property",
                    type: string
                },
                property_2: {
                    description: "second property",
                    type: string
                }
            }
        }
    }
}

有没有更好的方法来实现我所需要的？

Answer 1

通过使用其他属性：

definitions:
  String-StringStringMap: # <-- use this as your result
    type: object
    additionalProperties:
      $ref: "#/definitions/StringStringMap"

  StringStringMap:
      type: object
      additionalProperties:
        type: string

这产生了一个2级映射:

{
  "additionalProp1": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "additionalProp2": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "additionalProp3": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

有了同样的想法，你也可以指定一个3级地图。

Answer 2

如果我理解正确的话，基本问题是没有普遍接受的Java Map的JSON映射，尤其是当键比字符串更复杂的时候。我看到GSON采用了一种方法(将密钥视为对象)，而Jackson采用了另一种方法(将密钥序列化为字符串)。相当于Map(一个字典)的c#使用第三种方法(将每个条目视为一个独立的键值对象，具有称为“key”和“value”的属性)。由于Swagger试图成为语言和连续剧的不可知论者，这使它处于一个不可能的位置。

Answer 3

使用＜code＞additionalProperties＜/code＞是用OpenAPI（fka.Swagger）规范描述hashmap的正确方法，但Swagger UI目前不呈现它们。

此处跟踪了该问题https://github.com/swagger-api/swagger-ui/issues/1248

同时，您可以使用这个技巧：为相同类型的地图对象定义一个非必需的属性（default，在下面的示例中），并在描述中给出一些提示：

swagger: "2.0"
info:
  version: 1.0.0
  title: Hashmap
  
paths: {}

definitions:
  MapItem:
    properties:
      firstname:
        type: string
      lastname:
        type: string
  Map:
    description: a (key, MapItem) map. `default`is an example key
    properties:
      default:
        $ref: '#/definitions/MapItem'
    additionalProperties:
      $ref: '#/definitions/MapItem'