Swagger UI: Multiple anonymous objects in array

Question

I am writing Swagger documentation for an API, and one endpoint returns many nested objects and parameters.

There is one returned array, however, which does not return regular parameters. Instead, it returns two anonymous objects that hold the parameters.

"balanceDisplaySettings": [ 
  {
    "type": "Balance",
    "label": "Current",
    "visible": true,
    "primary": false
  },
  {
    "type": "AvailableBalance",
    "label": "Available",
    "visible": true, 
    "primary": true
  }
]

YAML

swagger: '2.0'
schemes:
 - https
consumes:
  - application/json
produces:
  - application/json
paths:
"/Path/":
     responses:
     '200':
      description: OK
      schema:
        type: object
        properties:
          balanceDisplaySettings:
            type: array
            items:
              type: object
              properties:
                type:
                  type: "Balance"
                  description: description
                label: 
                  type: "Available"
                  description: description
                visible:
                  type: boolean
                  description: description
                primary:
                  type: boolean
                  description: description
              type: object
              properties:
                type:
                  type: "AvailableBalance"
                  description: description
                label: 
                  type: "Available"
                  description: description
                visible: 
                  type: boolean
                  description: description
                primary:
                  type: boolean
                  description: description

Looking at swagger's documentation for Describing Request Body, there is seemingly no way to handle objects without a name.

How do I (Using YAML) document this type of response body in Swagger-UI?

Answer 1

An array of objects is defined like this:

type: array
items:
  type: object
  properties:
    prop1:
      type: string
    prop2:
      type: integer
    # etc.

In your example, the response contains an object with the property balanceDisplaySettings, and this property contains an array of objects. This can defined as follows:

paths:
  /Path:
    get:
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              balanceDisplaySettings:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    label: 
                      type: string
                    visible:
                      type: boolean
                    primary:
                      type: boolean

Note that the schema defines the response structure, meaning you don't need to specify the actual values ("Balance", "AvailableBalance", etc.) anywhere. However, if you want to display the example from your post (array with 2 objects) as an example in Swagger UI, you can add it like this:

              balanceDisplaySettings:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    label: 
                      type: string
                    visible:
                      type: boolean
                    primary:
                      type: boolean
                example:            # <-- example of array of 2 objects
                  - type: Balance
                    label: Current
                    visible: true
                    primary: false
                  - type: AvailableBalance
                    label: Available
                    visible: true
                    primary: true

Finally, you may want to split the inline nested schema to make the spec more modular.

paths:
  /Path:
    get:
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/MyResponseObject'
                                    #   |
definitions:                        #   |
  # TODO: better name               #   |
  MyResponseObject:    # <--------------+
    type: object
    properties:
      balanceDisplaySettings:
        type: array
        items:
          $ref: '#/definitions/BalanceDisplaySetting'
        example:                     #  |
          - type: Balance            #  |
            label: Current           #  |
            visible: true            #  |
            primary: false           #  |
          - type: AvailableBalance   #  |
            label: Available         #  |
            visible: true            #  |
            primary: true            #  |
                                     #  |
  BalanceDisplaySetting:     # <--------+
    type: object
    properties:
      type:
        type: string
        example: Balance
      label:
        type: string
        example: Current
      visible:
        type: boolean
      boolean:
        type: boolean