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?

user_8284324 · Answer

Another solution is the oneOF parameter. With it you can use multiple anonymous objects as you want.

Just create some definitions and call them inside items:

"type": "array",
"items": {
  "oneOf": [
    { "$ref": "#/components/schemas/Schema1" },
    { "$ref": "#/components/schemas/Schema2" }
  ]
}

You can read more about here:

https://community.smartbear.com/t5/Swagger-Open-Source-Tools/Can-You-Define-a-Response-Consisting-of-an-Array-With-Two/td-p/186919

Hope it helps

Swagger UI: Multiple anonymous objects in array

2 Answers