Create a swagger/open API response with array of un-named objects

Question

I get the response from an http request in the following form: it is an array of un-named array(s) and object(s). I cannot figure out the proper Swagger (Open API) specification for this case.

[
  [
    {
      "prop1": "hello",
      "prop2": "hello again"
    },
    {
      "prop1": "bye",
      "prop2": "bye again"
    }
  ],
  {
    "key": 123
  }
]

Possible duplicate of [How to create different element types within Swagger 2.0 editor](https://stackoverflow.com/questions/38690802/how-to-create-different-element-types-within-swagger-2-0-editor) and [Model response containing array of different object types in swagger](https://stackoverflow.com/q/41129403/113116). — Helen, Dec 11 '17 at 08:00

score 13 · Answer 1 · answered Dec 11 '17 at 08:13

The answer depends on which version of OpenAPI you use.

OpenAPI 3.0 supports oneOf, so it's possible to define multiple schemas for array items:

openapi: 3.0.0
...

paths:
  /something:
    get:
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:   # <---------
                    - type: array
                      items:
                        type: object
                        properties:
                          prop1:
                            type: string
                          prop2:
                            type: string
                    - type: object
                      properties:
                        key:
                          type: integer
                      required:
                        - key

OpenAPI 2.0 does not support oneOf or mixed types. The most you can do is use the typeless schema, which means the array items can be anything - objects, arrays or primitives - but you can't specify the exact types.

swagger: '2.0'
...
paths:
  /:
    get:
      produces:
        - application/json
      responses:
        '200':
          description: success
          schema:
            type: array
            items: {}   # <---------

            # Example to display in Swagger UI:
            example:
              - - prop1: hello
                  prop2: hello again
                - prop1: bye
                  prop2: bye again
              - key: 123

score 0 · Answer 2 · answered Mar 15 '23 at 15:08

You can mix Yaml with Json:

openapi: 3.0.3

  /users/all:
    get:
      tags:
        - Users
      summary: Get all datas.
      responses:
        "200":
          description: Create
          content:
            application/json:
              schema:
                type: array
                example:
                  [
                    {
                      "id": 1,
                      "prop1": "CRM",
                      "prop2": 30908,
                      "uf": "SP"
                    }
                  ]
      security:
        - isAuthorize: []

My environment:

{
  "os": "ubuntu-24.04",
  "node": "^18.x",
  "npm": "^9.x",
  "swagger-jsdoc": "^6.2.8",
  "swagger-ui-express": "^4.6.0",
}

score -3 · Answer 3 · answered Dec 11 '17 at 07:14

-3

I found a way, thanks:

"responses": {
      "200": {
        "description": "success",
        "schema": {
          "type": "array",
          "items": [{
           "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "prop1": {
                  "type": "string",
                },
                "prop2": {
                  "type": "string",
                }
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "number"
              }
            }
          }]
        }
      }
    }
  }

answered Dec 11 '17 at 07:14

amp

109
1
1
9

This definition is not valid, because `items` requires a single type and not an array. – Helen Dec 11 '17 at 08:03
Ya know, I saw this and giggled.. but then I was studying the JSON schema spec, and it looks like arrays ARE valid! See: https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.9.3.1 – Sean Aitken Mar 10 '20 at 17:35

Create a swagger/open API response with array of un-named objects

3 Answers3