您可以在查询和正文中混合使用 Swagger 的参数吗？

Question

我在尝试时遇到错误，但我想创建一个接受 2 个查询参数和 1 个正文项(名称列表(的端点。 当我在连接中运行它时，但说它是一个无效的规范。

/devices/list:
post:
tags: [Devices]
operationId: app.get_devices
summary: Gets a complete list of devices.
parameters:
- $ref: '#/parameters/foo-t'
- $ref: '#/parameters/bar-t'
- in: body
name: device_names
required: true
type: array
items:
type: string
description: a list of devices
...

它编译和运行时没有 - in： body 部分。 所以我知道这两个参数很好。 似乎我在向 python 发送 json 数组时遇到了问题。

显式返回的错误是：

connexion.exceptions.InvalidSpecification： {'in'： 'body'， 'name'： "device_names"， "必需"： 真， "类型"： "数组"， "项目"： {"类型"： "字符串"}， "说明"： "设备名称列表"} 在 任何给定的架构

验证"oneOf"失败 schema['properties']['paths']['patternProperties']['^/']['properties']['post']['properties']['parameters']['items']： {'oneOf'： [{'$ref'： '#/definitions/parameter'}， {'$ref'： '#/definitions/jsonReference'}]}

在实例['paths']['/devices/list']['post']['parameters'][2]上： {'description'： '设备名称列表'， "在"："身体"， 'items'： {'type'： 'string'}， "名称"： "device_names"， "必需"：真， 'type'： 'array'}

我想要的最终状态是我可以说：

//In javascript
$.post("devices/list", {device_names: ["a","b","c"]}, {params:{foo:1, bar:42}}).success( x => {
//...
});
# In Python3
def get_devices(foo, bar, device_names):
pass

Answer 1

是的，您可以混合使用查询和正文参数。

该错误是由 body 参数的语法不正确引起的。更改它，以便将type和items包装成schema，如下所示：

- in: body
name: device_names
required: true
schema:   # <-------
type: array
items:
type: string
description: a list of devices

在 OpenAPI 2.0 中，非正文参数(路径、查询、标头、表单参数(直接使用type关键字，但正文参数的类型必须包装成schema。

上面的示例匹配包含字符串数组的请求正文，如下所示 –["a", "b", "c"]。

如果数组应该包装到 JSON 对象中

{
"device_names": ["a", "b", "c"]
}

您需要更改 body 参数，如下所示：

- in: body
name: device_names
required: true
schema:
type: object
required: [device_names]
properties:
device_names:
type: array
items:
type: string
description: a list of devices