[Support] Swagger 如何支持参数是复杂类型的数组、返回值是复杂类型的数组？

[googoo625]

Describe the problem（描述问题）

使用 @midwayjs/swagger（版本 3.14.8），请教如何处理复杂参数和返回值的情况。

如下是一个接口定义：

	@Post("/apns", { summary: "接入点配置"})
	public async setEndPoints(@Query("id") id: number,  @Body() data: GroupEndPoint[]): Promise<RO<ApnParams>> {
	   //
	}

目前swagger得到的如下，requestBody部分和responses部分都没有体现出详细结构，请问如何配置能够改善？

	"post": {
		"summary": "接入点配置",
		"operationId": "envcontroller_setendpoints",
		"tags": ["env"],
		"requestBody": {
			"required": true,
			"description": "",
			"content": {
				"application/json": {
					"schema": {
						"type": "Array"
					}
				}
			}
		},
		"parameters": [{
			"name": "id",
			"in": "query",
			"required": false,
			"schema": {
				"type": "number"
			}
		}],
		"responses": {
			"200": {
				"description": "OK"
			}
		}
	}

Midway Versions（Midway 版本）

"dependencies": {
"@midwayjs/bootstrap": "^3.12.0",
"@midwayjs/core": "^3.12.0",
"@midwayjs/decorator": "^3.12.0",
"@midwayjs/info": "^3.12.0",
"@midwayjs/koa": "^3.12.0",
"@midwayjs/logger": "^2.14.0",
"@midwayjs/swagger": "^3.12.7",
"@midwayjs/validate": "^3.12.0",
},

[czy88840616]

https://midwayjs.org/docs/extensions/swagger#%E6%B3%9B%E5%9E%8B%E8%BF%94%E5%9B%9E%E6%95%B0%E6%8D%AE 这个？

[googoo625]

这个能解决返回值是带泛型的复杂类型的情况，还不太满足需求。

我希望的是两点：
1）Body参数是复杂类型的数组： @Body() data: GroupEndPoint[]
2）返回值是带泛型的复杂类型的数组（原问题返回值漏了数组符号）：Promise<RO<ApnParams[]>>

public async setEndPoints(@Query("id") id: number,  @Body() data: GroupEndPoint[]): Promise<RO<ApnParams[]>>

查文档一直没找到参数是数组该怎么写，只有参数类中属性是数组的说明。

[czy88840616]

按我的想法，应该是这样

@ApiBody({
  type: 'array',
  items: {
     type: GroupEndPoint
  }
})
async setEndPoints() {}

前提是 GroupEndPoint 中有 @ApiProperty 定义

[googoo625]

不行啊，ApiBodyOptions里没有items属性……
ApiPropertyOptions里才有。

文档里swagger部分还是不太充分，一直没找到办法。

[czy88840616]

哦，好像是，body 不能直接走 type，得在 content，定义是对的。

@ApiBody({
        content: {
          'application/json': {
            schema: {
              type: 'array',
              items: {
                $ref: getSchemaPath(GroupEndPoint),
              },
            },
          },
        },
      })

[googoo625]

问题解决，非常感谢。
增加了一些类型定义，最终参数是数组和返回值是泛型+数组的情况都得到了解决。