Swagger: map of <string, Object> : <p>I need to document with Swagger an API that uses, both as input and output, maps of objects, indexed by string keys.</p>

<p>Example:</p>

<pre><code>{
    "a_property": {
        "foo": {
            "property_1": "a string 1",
            "property_2": "a string 2"
        },
        "bar": {
            "property_1": "a string 3",
            "property_2": "a string 4"
        }
    }
}
</code></pre>

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

<p>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:</p>

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

<p>I have read the <a href="https://github.com/OAI/OpenAPI-Specification/issues/38" rel="noreferrer">'Open API Specification' - 'Add support for Map data types #38'</a> page. As far as I understand, it recommends to use <strong>additionalProperties, but it doesn't seem to answer my need</strong> (or it doesn't work with Swagger UI 2.1.4 that I use). <strong>Did I miss something?</strong></p>

<p>So far I have found the following work-around (in Swagger JSON):</p>

<pre><code>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
                }
            }
        }
    }
}
</code></pre>

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

<p><strong>Is there a better way to achieve what I need?</strong></p>
