Swagger OpenAPI array documentation in response

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

Jack · Accepted Answer · 2021-10-20 13:40:35Z

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'

Collectives™ on Stack Overflow

Swagger OpenAPI array documentation in response

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related