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
}
]
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
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",
}
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"
}
}
}]
}
}
}
}
items requires a single type and not an array.