Swagger:<字符串，对象>的映射 [英] Swagger: map of &lt;string, Object&gt;

问题描述

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

I need to document with Swagger an API that uses, both as input and output, maps of objects, indexed by string keys.

示例:

{
    "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" 可以是任何字符串键，但它们在键集中应该是唯一的.

"foo" and "bar" can be any string keys, but they should be unique among the set of keys.

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

I know that, with Swagger, I can define an array of objects, but this gives a different API since we then would have something as:

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

我已阅读 'Open API Specification' - 'Add support for Map data types #38' 页.据我了解，它建议使用 additionalProperties，但它似乎不能满足我的需要(或者它不适用于我使用的 Swagger UI 2.1.4).我错过了什么吗?

I have read the 'Open API Specification' - 'Add support for Map data types #38' page. As far as I understand, it recommends to use additionalProperties, but it doesn't seem to answer my need (or it doesn't work with Swagger UI 2.1.4 that I use). Did I miss something?

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

So far I have found the following work-around (in 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"可以是任何字符串，并且可以重复多次.

This almost does the job, but the reader has to understand that "key" can be any string, and can be repeated several times.

是否有更好的方法来实现我的需求?

推荐答案

使用 additionalProperties 是使用 OpenAPI (fka. Swagger) 规范描述 hashmap 的正确方法，但 Swagger UI 暂时不渲染它们.

Using additionalPropertiesis the proper way to describe hashmap with OpenAPI (fka. Swagger) Specification but Swagger UI do not render them for now.

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

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

Meanwhile you can use this trick: define a non required property (defaultin the example below) of the same type of the map's objects and give some hint within the description:

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 合同并改进文档.

This description does not modify API contract and improves documentation.

这篇关于Swagger:<字符串，对象>的映射的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！