如何在OpenAPI 2.0(Swagger 2.0)中拥有多个主体参数

Question

我希望在请求主体中有多个参数，如下所示，但Swagger Editor说"不允许使用多个身体参数"；。如何将对象和基元类型组合在一个POST主体中？

我期望criteria对象和两个基元字段(offset，limit(，如下所示：

{
"criteria": {
"key": "CBC",
"code":
},
"offset": 5,
"limit" : 5
}

OpenAPI定义：

"paths": {
"/user": {
"post": {
"tags": [
"user Service"
],
"summary": "Returns a list of user",
"operationId": "searchUsers",
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "criteria",
"required": true,
"schema": {
"$ref": "#/definitions/Criteria"
}
},
{
"name": "offset",
"type": "integer",
"description": "The offset for pagination.",
"format": "int32",
"default": 0,
"minimum": 0,
"required": false,
"in": "body"
},
{
"name": "limit",
"type": "integer",
"description": "The maximum number user",
"format": "int32",
"minimum": 1,
"maximum": 30,
"default": 30,
"required": false,
"in": "body"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/user"
}
},
definitions:
"Criteria": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"description": "search key.",
"pattern": "[A-Za-z0-9-]+",
"minLength": 1,
"maxLength": 30
},
"code": {
"type": "string",
"description": "emp code filter on.",
"pattern": "^[A-Za-z0-9]+",
"minLength": 0,
"maxLength": 9
}

}
},

如何保留对象和基元类型？

Answer 1

您就快到了。

这部分是如何在OpenAPI 2.0:中定义请求主体

"parameters": [
{
"in": "body",
"name": "criteria",
"required": true,
"schema": {
"$ref": "#/definitions/Criteria"
}
},

也就是说，它被定义为in: body参数，但schema必须描述整个请求主体对象，而不是单个字段。

正确的版本是：

"paths": {
"/user": {
"post": {
...
"parameters": [
{
"in": "body",
"name": "criteria",
"required": true,
"schema": {
"$ref": "#/definitions/UserSearchParams"
}
}
],
"responses": {
...
}
}
}
},
"definitions": {
"UserSearchParams": {
"type": "object",
"properties": {
"criteria": {
"$ref": "#/definitions/Criteria"
},
"offset": {
"type": "integer",
"description": "The offset for pagination.",
"format": "int32",
"default": 0,
"minimum": 0
},
"limit": {
"type": "integer",
"description": "The maximum number user",
"format": "int32",
"minimum": 1,
"maximum": 30,
"default": 30
}
}
},
"Criteria": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"description": "search key.",
"pattern": "[A-Za-z0-9-]+",
"minLength": 1,
"maxLength": 30
},
"code": {
"type": "string",
"description": "emp code filter on.",
"pattern": "^[A-Za-z0-9]+",
"minLength": 0,
"maxLength": 9
}
}
},
...
}
}