如何在 Swagger 中定义包含复杂对象数组的示例请求主体？

Question

我正在尝试为将对象数组作为请求正文发布的服务编写 Swagger 规范。我希望用户能够使用数组中一组特定的多个不同复杂对象作为默认样本输入来测试服务。

到目前为止，我有以下定义服务和复杂对象的代码：

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

输出数组正确返回，但模型架构中只有一项。

如何使示例请求正文包含数组中的多个不同项？

Answer 1

我能够通过在对象定义上使用示例属性并用 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

如何在 Swagger 中定义包含复杂对象数组的示例请求主体？

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

yaml

express

swagger

openapi