How to define an example request body containing an array of complex objects in Swagger?

Question

I am trying to write the Swagger spec for a service that posts an array of objects as request body. I would like the user to be able to test the service with a specific set of multiple different complex objects in the array as the default sample inputs.

So far I have the following code defining the service and complex object:

paths:
    /myService
        post:
            summary: test 123
            description: test 123
            parameters:
                - name: bodyParamsObject
                  description: 'Object containing any / all params in the body'
                  in: body
                  required: true
                  schema:
                    properties:
                        data:
                            $ref: '#/definitions/myInputArray'
            responses:
                200:
                    description: OK
                    schema: myOutputArray

definitions:
    myInputArray:
        type: array
        items:
            $ref: '#/definitions/myComplexObject'

    myOutputArray:
        type: array
        items:
            $ref: '#/definitions/myComplexObject'

    myComplexObject:
        type: object
        properties:
            description:
            type: string
            example: 'Example Item'     
        size:
            example: 552
            type: integer
            format: int32
        hasAdditionalProperties:
            type: boolean
            example: true

The output array is coming back correctly, but there is only one item in the model schema.

How can I make the sample request body contain multiple different items in the array?

Possible duplicate of Return an array of object in Swaggerhub — Helen
– Helen, Commented Apr 19, 2018 at 20:30
Nope. This one is about input parameters within a POST request body, not outputs from a GET operation. — John Meyer
– John Meyer, Commented Apr 19, 2018 at 20:48
It's mostly the same because the real question here and there is "how to specify an array example containing multiple items?" — Helen
– Helen, Commented Apr 19, 2018 at 21:17
I disagree, I think this question specifically addresses the request body of a POST operation which should contain multiple different items in an array. In any case I think this question adds value as it also illustrates how to do a default request body in addition to the array of different items as inputs. — John Meyer
– John Meyer, Commented Apr 19, 2018 at 23:46

John Meyer · Accepted Answer · 2018-04-19 23:48:01Z

I was able to solve this by using the example property on the object definition and filling it with the array in json.

definitions:
    myInputArray:
        type: array
        items:
            $ref: '#/definitions/myComplexObject'
        example: [
                    {
                        "description": "Example Item 1",
                        "hasAdditionalProperties": true,
                        "size": 750,
                    },
                    {
                        "description": "Another example",
                        "hasAdditionalProperties": false,
                        "size": -22,
                    },                                
                    {
                        "description": "Last one",
                        "hasAdditionalProperties": true,
                        "size": 0,
                    }
                ]

    myComplexObject:
        type: object
        properties:
            description:
            type: string
            example: 'Example Item'     
        size:
            example: 552
            type: integer
            format: int32
        hasAdditionalProperties:
            type: boolean
            example: true

Taft Wallace · Accepted Answer · 2023-04-24 14:31:44Z

0

/**
 * @swagger
 * components: 
 *    schemas:
 *      JSBaseItem:
 *        type: object
 *        properties:
 *          name:
 *            type: string
 *            description:  The skill name for the job req
 *          weight: 
 *            type: integer
 *            description: The value assigned to the skill name 
 */

/**
 * @swagger
 * components: 
 *    schemas:
 *      JobSearchItem:
 *        type: object
 *        properties:
 *          skills:
 *            type: array
 *            description:  The skill name for the job req
 *            items:
 *               $ref: '#/components/schemas/JSBaseItem'
 *          position: 
 *            type: array
 *            description: The value assigned to the skill name 
 *            items:
 *               $ref: '#/components/schemas/JSBaseItem'
 * 
 */


 *      requestBody:
 *        required: true
 *        content: 
 *          application/json:
 *            schema: 
 *               type: object
 *               items:
 *                 $ref: '#/components/schemas/JobSearchItem'
 *            example: {"skills":[{"name":"skillname","weight": 0}],"position":[{"name":"positionname","weight": 0}]}

To get an example of my complex JSON message to appear as an example in my Swagger Documentation, I had to write the example message keeping on a single line.

edited Apr 24, 2023 at 14:31

answered Apr 20, 2023 at 15:21

Taft Wallace

113 bronze badges

1 Comment

Community Over a year ago

As it’s currently written, your answer is unclear. Please edit to add additional details that will help others understand how this addresses the question asked. You can find more information on how to write good answers in the help center.

Collectives™ on Stack Overflow

How to define an example request body containing an array of complex objects in Swagger?

2 Answers 2

Comments

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related