SpringDoc v1.6.12中POST表单参数API文档生成异常求助

你遇到的问题是SpringDoc默认行为导致的：@RequestParam注解的参数会被默认解析为URL查询参数，即便接口指定了consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE。要让OpenAPI文档生成符合预期的表单请求体结构，有两种常用解决方案：

方案1：使用DTO + @ModelAttribute（推荐） #

创建包含所有请求参数的DTO类，通过@ModelAttribute接收表单数据，SpringDoc会自动将其识别为application/x-www-form-urlencoded类型的请求体：

步骤1：定义参数DTO #

public class LoadTaskRequest {
    // 可添加JSR-380校验注解，SpringDoc会自动识别必填项
    @NotBlank
    private String applicationId;
    
    @NotBlank
    private String businessId;
    
    private boolean directLink;

    // 生成getter和setter方法
    public String getApplicationId() { return applicationId; }
    public void setApplicationId(String applicationId) { this.applicationId = applicationId; }
    public String getBusinessId() { return businessId; }
    public void setBusinessId(String businessId) { this.businessId = businessId; }
    public boolean isDirectLink() { return directLink; }
    public void setDirectLink(boolean directLink) { this.directLink = directLink; }
}

步骤2：修改Controller方法 #

@PostMapping(path = TASK_MAPPING_PATH, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public ResponseEntity<String> loadTask(@ModelAttribute LoadTaskRequest request) {
    // 从request对象中获取参数：request.getApplicationId()、request.getBusinessId()、request.isDirectLink()
    [...]
}

这种方式既能让OpenAPI文档生成正确的请求体结构，还能让代码更整洁，方便后续参数扩展。

方案2：使用SpringDoc注解手动声明请求体 #

如果不想创建DTO，可以通过@io.swagger.v3.oas.annotations.parameters.RequestBody注解手动定义请求体结构，强制覆盖SpringDoc的默认解析：

@PostMapping(path = TASK_MAPPING_PATH, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
@io.swagger.v3.oas.annotations.parameters.RequestBody(
    content = @Content(
        mediaType = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
        schema = @Schema(
            type = SchemaType.OBJECT,
            required = {"applicationId", "businessId", "directLink"},
            properties = {
                @Schema(name = "applicationId", type = SchemaType.STRING),
                @Schema(name = "businessId", type = SchemaType.STRING),
                @Schema(name = "directLink", type = SchemaType.BOOLEAN)
            }
        )
    )
)
public ResponseEntity<String> loadTask(
      @RequestParam String applicationId,
      @RequestParam String businessId,
      @RequestParam boolean directLink
) {[...]}

这种方式不需要修改参数接收逻辑，但参数较多时注解会显得冗长，维护成本较高。

内容的提问来源于stack exchange，提问作者Jonathan Kaeser