Swagger：GET 请求中的 Spring MVC 模型

Question

在 MVC 中，您会期望控制器接收模型作为输入并生成模型作为输出。在 Swagger 中，后者不是问题，但我对前者有问题。我不明白如何让 Swagger 从传入的 GET 参数构建输入模型。

考虑：

"paths": {
    "/search": {
        "get": {
            "consumes": [],
            "produces": [
                "application/json"
            ],
            "parameters": [
                // What goes here?
            ],
            "responses": {
                "200": {
                    "description": "Success",
                    "schema": { 
                        "$ref": "#/definitions/SearchResponse"
                    }
                },
            }
        }
    }
}

如何使生成的控制器的方法具有如下签名：

    public ResponseEntity<ResultModel> controllerGet(ModelFromParameters input);

其中 ModelFromParameters 会有几个字段对应不同的 GET 参数。

示例主要关注 POST 请求或 GET 请求，其中 20 多个参数中的每一个都填充在方法的参数列表中，这显然是反 MVC。

所讨论的 API 是一个复杂的无状态查询系统，有很多参数。

Answer 1

假设：您希望创建一个对象作为服务方法的参数，但仍将对象的每个字段作为实际 http 请求中的查询参数传递，并且能够以 swagger 记录各个字段。

例如获取http://localhost:8080/search?parameter1=value1&parameter2=value2

典型的服务方法定义，其中每个查询参数都定义为实际方法中的参数

@RequestMapping(method = RequestMethod.GET)
public ResponseEntity<List<String>> search(@RequestParam parameter1, @RequestParam parameter2) {
...
}

使用带有 @ModelAttribute 注释的 Object（a.k.a Bean）修改了具有单个参数的服务方法。虽然它是一个对象，但就 REST API 而言，它仍然与上面相同。

@RequestMapping(method = RequestMethod.GET)
public ResponseEntity<List<String>> search(@ModelAttribute FormParam formParam) {
...
}

FormParam 类。您可以使用 @ApiParam

记录每个字段

public class FormParam {
    @ApiParam(value = "parameter1 - description here", required = true)
    private String parameter1;
    @ApiParam(value = "parameter2 - description here", required = true)
    private String parameter2;
    //define getter setters below
}

这就是它在招摇中的表现

这是生成的 swagger.json sn-p

"paths": {
    "/search": {
        "get": {
            "tags": ["search-service"],
            "summary": "Search with Object as parameter",
            "description": "Search with Object as parameter",
            "operationId": "searchUsingGET",
            "consumes": ["application/json"],
            "produces": ["*/*"],
            "parameters": [{
                "name": "parameter1",
                "in": "query",
                "description": "parameter1 - description here",
                "required": true,
                "type": "string"
            },
            {
                "name": "parameter2",
                "in": "query",
                "description": "parameter2 - description here",
                "required": true,
                "type": "string"
            }],
            "responses": {
                "200": {
                    "description": "OK",
                    "schema": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "401": {
                    "description": "Unauthorized"
                },
                "403": {
                    "description": "Forbidden"
                },
                "404": {
                    "description": "Not Found"
                }
            }
        }
    },

如果您手动创建 swagger.json，则可以记录查询参数

"parameters": [{
    "name": "parameter1",
    "in": "query",
    "description": "parameter1 - description here",
    "required": true,
    "type": "string"
},
{
    "name": "parameter2",
    "in": "query",
    "description": "parameter2 - description here",
    "required": true,
    "type": "string"
}],

Answer 2

我认为你不能。对于列表页面+搜索，我也有类似的问题，使用 GET 和正文。没有办法让大摇大摆地代表这一点，即使它在 Tomcat 中也有效； Elasticsearch 也支持它。看起来没有计划大摇大摆地改变这方面。我采用招摇将两者分开：list-without-search 为 GET，list+search 为 POST，只是为了将页面放入 swagger 文档中，如果后者实际上也可以作为 GET。

我没有使用 swagger 代码生成的经验，但是，如果您的配置使用 POST 生成了您期望的结果，但使用 GET 没有生成，那么您可能遇到了同样的限制。

https://github.com/swagger-api/swagger-ui/issues/2867

https://github.com/swagger-api/swagger-ui/issues/2136

https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#operationRequestBody

仅在 HTTP 1.1 规范 RFC7231 明确定义了请求正文语义的 HTTP 方法中才支持 requestBody。在 HTTP 规范含糊不清的其他情况下，requestBody 应被消费者忽略。

Answer 3

通常，http 服务器（例如 tomcat、jetty）不会接受 get 请求中的正文消息。如果客户端需要通过 http get 方法向服务器传递参数，它应该使用 query string 。 '?' 之后的 URL 的最后一部分特点。查询字符串详情可以看query string

但是在 spring mvc 的帮助下，查询字符串中的 http 请求参数将绑定到控制器方法参数的字段。所以看起来客户端向服务器端传递了一个 pojo 参数。

参数部分应如下所示：

"parameters" : [ {
      "name" : "age",
      "in" : "query",
      "required" : false,
      "type" : "integer"
    }, {
      "name" : "firstName",
      "in" : "query",
      "required" : false,
      "type" : "string"
    }]

请注意，“in”字段的值为“query”。这意味着参数是通过查询字符串传递的。

Answer 4

我想你需要的是在请求正文中发布你的参数，它是这样的：

...
{
  "name": "files",
  "in": "body",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "$ref": "#/definitions/FileRequest"
    }
  }
}

翻译为：

public Response storageFilePost(
            @NotEmpty(message = "systemID is required!") @QueryParam("systemID") final String systemID,
            @NotNull(message = "qParam is required!") @QueryParam("qParam") final Long qParam,
            @NotNull(message = "files are required!") final List<FileRequest> files) {