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 中记录各个字段。

例如 GET http://localhost:8080/search?parameter1=value1¶meter2=value2

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

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

使用带有@ModelAttribute注释的 Object（又名 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片段

"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 和正文。没有办法让 swagger 代表这一点，即使它在 Tomcat 中也有效；Elasticsearch也支持它。看来swagger并没有打算改变这方面的事情。我求助于将两者分开：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

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