Swagger:<string, Object> 的映射 [英] Swagger: map of <string, Object>

问题描述

我需要使用 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' - '添加对地图数据类型的支持#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:<string, Object> 的映射的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！