如何为Spring中@RequestBody参数添加Swagger UI描述？

先纠正一个关键问题：你的控制器方法里用了两个@RequestBody注解，这不符合Spring MVC规则——一个POST请求只能解析一次请求体，所以必须去掉其中一个，或者调整参数结构（比如把newJson的内容整合到GetdocprintRequest里，或者用请求参数传递）。

接下来是给@RequestBody参数添加自定义描述的具体步骤：

1. 用@ApiParam注解自定义参数描述 #

在@RequestBody修饰的参数上添加Swagger的@ApiParam注解，通过name和value属性设置参数的名称和描述，替换默认的参数名显示。

修改后的控制器代码示例：

@ApiOperation(value = "用于打印报价单文档", response = GenerateDocPrintResponse.class)
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "成功获取数据"),
        @ApiResponse(code = 401, message = "您无权访问该资源"),
        @ApiResponse(code = 403, message = "禁止访问该资源"),
        @ApiResponse(code = 404, message = "未找到指定资源")
})
@RequestMapping(value = "/service/generateDocPrint", method = RequestMethod.POST)
public @ResponseBody String generateDocPrint(
        @ApiParam(name = "打印请求参数", value = "包含请求头和打印负载的完整请求对象") 
        @RequestBody GetdocprintRequest printRequest,
        HttpServletRequest request, 
        HttpServletResponse response) throws Exception {
    // 你的业务逻辑代码
}

2. 给POJO字段添加描述 #

通过@ApiModelProperty注解给GetdocprintRequest的每个字段添加描述，这样Swagger UI里会展示每个字段的详细说明，让接口文档更清晰。

修改后的POJO代码示例：

package com.iii.fw.models.generatedocprint;
import com.iii.fw.models.common.RequestHeader;
import io.swagger.annotations.ApiModelProperty;

public class GetdocprintRequest {   
    @ApiModelProperty(value = "请求头信息，包含认证、标识等通用参数")
    RequestHeader reqHeader;
    
    @ApiModelProperty(value = "打印请求负载，包含具体的打印配置和文档信息")
    private ReqPayloadGDP reqPayload;
    
    public ReqPayloadGDP getReqPayload() {
        return reqPayload;
    }

    public void setReqPayload(ReqPayloadGDP reqPayload) {
        this.reqPayload = reqPayload;
    }

    public GetdocprintRequest withReqPayload(ReqPayloadGDP reqPayload) {
        this.reqPayload = reqPayload;
        return this;
    }
    
}

关键说明 #

• 移除冗余@RequestBody：Spring MVC只允许一个方法有一个@RequestBody，否则会抛出解析异常，这是必须先解决的问题。
• @ApiParam的作用：直接覆盖Swagger默认显示的参数名和描述，让接口文档里的参数说明更贴合业务场景。
• @ApiModelProperty的作用：给POJO的每个字段补充说明，Swagger会自动在文档里展开显示这些描述，方便调用方理解参数结构。

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