Swagger OpenAPI array documentation in response - swagger

Question

How a Json like this be documented inside response section in swagger?
{
"data": [{
"id": "",
"name": "James",
"chat": "1",
"messages": {
"current": null,
"count": null,
"length": null,
"rows": null,
"type": null
},
"cid": "204",
"cat": "messages",
"mark": false
}],
"total": 200,
"action": "success"
}
I tried
responses:
'200':
description: test data
content:
application/json:
schema:
example:
- id: null
name: James
chat: 1
messages:
current:
count:
length:
rows:
type:
cid: 204
cat: chat
mark: false
totalCount: 200
action: success
But show error bad indentation of a mapping entry

Answer 1

You have to define the expected object structure as a separate schema in the #/components/schemas section.
For example you name the resulting model ResponseObj, which has the properties data, total and action. The data property is another complex type with its own properties, so you also define a model for that type. This continues until you have defined all the models down to their simple property types.
Here is the definition for your example:
components:
schemas:
ResponseObj:
properties:
data:
type: array
items:
$ref: '#/components/schemas/DataObj'
total:
type: string
action:
type: string
DataObj:
properties:
id:
type: string
name:
type: string
chat:
type: string
messages:
type: array
items:
$ref: '#/components/schemas/MessageObj'
cid:
type: number
cat:
type: string
mark:
type: boolean
MessageObj:
properties:
current:
type: string
count:
type: string
length:
type: number
rows:
type: number
type:
type: string
Now you can reference the ResponseObj model as the expected result of your operation:
paths:
/example:
get:
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ResponseObj'