Java OpenAPI/Swagger：POST请求体无法获取默认示例值，接收为null

问题原因 #

直接使用List<Long>作为@RequestBody参数时，Swagger无法自动识别正确的请求体格式，同时Spring MVC在解析纯JSON数组类型的请求体时，容易出现解析失败导致参数为null的情况。

解决方案 #

1. 将List包装为实体类（推荐） #

Spring对对象结构的JSON解析支持更稳定，创建一个DTO类包装List：

public class AdjustmentListRequest {
    private List<Long> adjList;

    // 生成getter、setter方法
    public List<Long> getAdjList() {
        return adjList;
    }

    public void setAdjList(List<Long> adjList) {
        this.adjList = adjList;
    }
}

修改接口方法，接收包装后的DTO：

@Operation(summary = "pushAdjustmentList")
@PostMapping(value = "/push/adjList")
public ResponseEntity<String> pushAdjustmentList(
        @RequestBody(description = "List of Adjustment Ids", required = true) AdjustmentListRequest request) {
    HttpStatus status = HttpStatus.OK;
    String response = null;
    List<Long> adjList = request.getAdjList();
    log.debug("Adjustments list submitted : {}", adjList);
    try {
        response = producerService.pushAdjustmentList(adjList);
    } catch (Exception ex) {
        log.error(LOGGER_COULD_NOT_PROCESS_REQUEST, ex.getMessage());
        response = ex.getMessage();
        status = HttpStatus.INTERNAL_SERVER_ERROR;
    }
    return ResponseEntity.status(status).body(response);
}

这样Swagger会自动生成包含adjList字段的JSON示例，Spring也能正确解析请求体。

2. 直接配置Swagger示例与请求格式（不包装类） #

如果坚持使用纯数组作为请求体，需要显式配置Swagger的示例和请求体格式：

@Operation(summary = "pushAdjustmentList")
@PostMapping(value = "/push/adjList")
public ResponseEntity<String> pushAdjustmentList(
        @RequestBody(description = "List of Adjustment Ids", required = true, 
            content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
                schema = @Schema(type = "array", implementation = Long.class),
                examples = @ExampleObject(value = "[123, 456, 789]"))) 
        List<Long> adjList) {
    // 原有业务逻辑
}

调用接口时，请求体必须是纯JSON数组（如[1001, 1002]），且请求头需设置Content-Type: application/json。

3. 检查Spring MVC JSON解析配置 #

确保项目已引入Jackson依赖（Spring Boot starter-web默认包含），如果是手动配置Spring MVC，需确认MappingJackson2HttpMessageConverter已注册，保证JSON请求体能被正确解析。

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