Swagger：<字符串，对象> 的映射

我需要使用 Swagger 记录一个 API，该 API 使用对象映射作为输入和输出，并通过字符串键进行索引。

Example:

{
    "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 的支持”页。据我了解，建议使用extraProperties，但它似乎不能满足我的需求（或者它不适用于我使用的 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
                }
            }
        }
    }
}

这几乎完成了工作，但是读者必须理解“key”可以是任何字符串，并且可以重复多次。

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

Using additionalProperties是使用 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'

此描述不会修改 API 契约并改进文档。