如何将springdoc与@PostMapping(consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)和@RequestParam一起使用

Question

我正在将项目从 SpringFox 升级到 SpringDoc v1.6.12，我努力使新代码适用于我的 RestController 的以下方法：

@PostMapping(path = TASK_MAPPING_PATH, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public ResponseEntity<String> loadTask(
      @RequestParam String applicationId,
      @RequestParam String businessId,
      @RequestParam boolean directLink
) {[...]}

此方法的特殊性在于，由于使用了 Content-Type application/x-www-form-urlencoded，因此它应该在正文中对其参数进行编码。

但是当我浏览网址https://localhost:8443/v3/api-docs时，生成的代码如下：

"/api/enrolment/task" : {
      "post" : {
        "operationId" : "loadTask",
        "parameters" : [ {
          "in" : "query",
          "name" : "applicationId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "in" : "query",
          "name" : "businessId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "in" : "query",
          "name" : "directLink",
          "required" : true,
          "schema" : {
            "type" : "boolean"
          }
        } ],
        "responses" : {
          [...]
        },
        "summary" : [...],
        "tags" : [...]
      }
    },

所有

applicationId

、

businessId

和

directLink

参数都在 URL 中传递，而不是按预期在请求正文中传递。

我本来期望使用以下 openApi 定义：

"/api/enrolment/task" : {
      "post" : {
        "operationId" : "loadTask",
        "requestBody" : {
          "content" : {
            "application/x-www-form-urlencoded" : {
              "schema" : {
                "type" : "object",
                "properties" : {
                  "applicationId" : {
                    "type" : "string"
                  },
                  "businessId" : {
                    "type" : "string"
                  },
                  "directLink" : {
                    "type" : "boolean"
                  }
                },
                "required" : [ "applicationId", "businessId", "directLink" ]
              }
            }
          }
        },
        "responses" : {
          [...]
        },
        "summary" : [...],
        "tags" : [...]
      }
    },

有人遇到过同样的问题吗？ 有谁知道我的问题的解决方案？ 谢谢。

Answer 1

答案很晚，但可能对某人有用。 我面临同样的问题，并且有示例如何使 springdoc 正确生成规范。

方法示例：

@PostMapping(
        consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
        produces = MediaType.APPLICATION_XML_VALUE)
@TokenRequestBodyDescription
public ResponseEntity<?> token(
         @Parameter(hidden = true) @RequestParam(value = "grantType", required = true) String grantType,
         @Parameter(hidden = true) @RequestParam(value = "refreshToken", required = false) String refreshToken,
         @Parameter(hidden = true) @RequestParam(value = "username", required = false) String username,
         @Parameter(hidden = true) @RequestParam(value = "password", required = false) String password,
         @Parameter(hidden = true) @RequestParam(value = "logonProvider", required = false) String logonProvider,
         @Parameter(hidden = true) @RequestParam(value = "mode", required = false) String mode,
        HttpServletRequest request) {
        //some logic here
}

@Parameter(hidden = true) 用于隐藏此参数作为查询参数处理

这是@TokenRequestBodyDescription的内容

@RequestBody(
        content = @Content(
                mediaType = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
                schemaProperties = {
                        @SchemaProperty(
                                name = "grantType",
                                schema = @Schema(
                                        allowableValues = {"password", "refresh_token"},
                                        requiredMode = Schema.RequiredMode.REQUIRED,
                                        description = "Grant type to token request operation",
                                        defaultValue = "password"
                                )
                        ),
                        @SchemaProperty(
                                name = "refreshToken",
                                schema = @Schema(description = "Refresh token (for 'refresh_token' grantType)")
                        ),
                        @SchemaProperty(
                                name = "username",
                                schema = @Schema(description = "User name (for 'password' grantType)")
                        ),
                        @SchemaProperty(
                                name = "password",
                                schema = @Schema(description = "User password (for 'password' grantType)")
                        ),
                        @SchemaProperty(
                                name = "logonProvider",
                                schema = @Schema(
                                        allowableValues = {"VALUE1", "VALUE2"},
                                        description = "Logon provider (for 'password' grantType)"
                                )
                        ),
                        @SchemaProperty(
                                name = "mode",
                                schema = @Schema(
                                        allowableValues = {"MODE1", "MODE2"},
                                        description = "Authorization mode"
                                )
                        )
                })
)
@Target(METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface TokenRequestBodyDescription {
}

看起来很难看，因为我们将 swagger 的参数声明和它的描述拆分在单独的文件中，但它确实有效。

结果截图：ui 中的方法看起来像，尝试一下”看起来像