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?

Helen · Accepted Answer · 2017-08-05 15:44:08Z

10

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

edited Aug 5, 2017 at 15:44

answered Aug 1, 2017 at 20:58

Helen

99.8k18 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

8 Comments

Arlo Over a year ago

I'm getting the error "Duplicated mapping key" in the online Swagger Editor when adding multiple objects to the array

Helen Over a year ago

@ChuckFecht, can you post the YAML code you're using? (e.g. update this question or post a new one)

Arlo Over a year ago

Updated the question

Helen Over a year ago

@ChuckFecht, your spec is not valid and indentations are wrong. I updated the answer.

Arlo Over a year ago

I'm trying to use multiple objects in an array, not just one. The problem is using more than one results in the error Duplicated mapping key

|

Joabe Leão · Accepted Answer · 2022-07-05 14:27:36Z

5

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

answered Jul 5, 2022 at 14:27

Joabe Leão

1262 silver badges3 bronze badges

1 Comment

claudius Over a year ago

That's pretty worked for me.

Collectives™ on Stack Overflow

Swagger UI: Multiple anonymous objects in array

2 Answers 2

8 Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

8 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related