3

I'm struggling with how to define a dictionary type in swagger editor. One of the parameters to my POST method is called 'roles' and it's value is a dictionary where the key is the email address and the value is an integer.

Gargoyle
  • 9,590
  • 16
  • 80
  • 145
  • Related: [Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0](http://stackoverflow.com/questions/41239913), [Swagger complex response model with dynamic key value hash maps](https://stackoverflow.com/questions/41097913) – Helen Jan 26 '17 at 11:06

1 Answers1

1

Swagger supports associative arrays/hashmaps/dictionaries where keys are strings. A dictionary is defined by using an object schema with the additionalProperties keyword specifying the value type of key/value pairs. The key type is not mentioned because keys are always strings.

So a string-to-integer dictionary can be defined as:

definitions:
  MyDictionary:
    type: object
    additionalProperties:
      type: integer


By default, Swagger UI 3.x and Swagger Editor 3.x render dictionaries as containing properties named additionalProp*:

enter image description here

If you want a more meaningful example, add an example to your dictionary schema:

definitions:
  MyDictionary:
    type: object
    additionalProperties:
      type: integer
    example:
      apples: 5
      oranges: 7
Helen
  • 87,344
  • 17
  • 243
  • 314
  • 2
    That doesn't really show up as anything in the UI though. I added a description property to the definition but Swagger UI doesn't display it. It also doesn't display the fact that it's a string key and integer value. It just says "MyDictionary" for example as the type. The third issue is that even though the 'roles' parameter is listed as required in the schema of the POST method, it stops having a red * on it when I switch it to reference this type. – Gargoyle Jan 26 '17 at 15:27
  • @Gargoyle: Dictionaries are rendered now in Swagger UI/Editor 3.x. I updated the answer. Not sure what you mean by "it stops having a red * on it when I switch it to reference this type" though. – Helen Jul 18 '17 at 19:29