Add dictionary value schema definition in Swagger spec

[kathleenkusworo]

Right now, I believe Dict fields are renderd as a generic Swagger object without further info of the dictionary values' schema. The code in Flask-Rebar is here.

Let's say we have the following Marshmallow schema:

class ComplexDict(Schema):
  dictionary = fields.Dict(
     keys=fields.String(),
     values=fields.Nested(ComplexObject),
     required=True,
  )

Based on Swagger 2.0 docs, the canonical way to define a String -> ComplexModel dictionary would be:

ComplexDict:
  type: object
  additionalProperties:
    $ref: '#/definitions/ComplexModel'

But, Flask-rebar will only render it as:

ComplexDict:
  type: object

We have been using a custom converter to work around this, see code snippet here. We can reasonably get to a point where we keep unfurling the definition of ComplexModel directly in-line within additionalProperties, like:

ComplexDict:
  type: object
  additionalProperties:
    items:
       additionalProperties: false
       description: The complex model
       properties:
           id:
              type: string
       type: object
       title: ComplexModel

but it will be ideal to get to a point where it makes a reference to the definition.