SpringDoc OpenAPI 中@PostMapping与@NotEmpty注解的协同使用问题解析

问题背景

在使用SpringDoc OpenAPI为Spring Boot 2.7项目生成API文档时，开发人员遇到了一个关于参数生成的特殊情况。当在POST请求方法中同时使用@PostMapping和@NotEmpty注解时，文档生成结果与预期不符。

问题现象

开发人员定义了一个POST接口方法，代码如下：

@Operation(summary = "关联用户和角色")
@PostMapping("/bindUserRoles")
public Result<Void> bindUserRoles(@NotNull Long userId, @NotEmpty List<Long> roleIds) {
    return Result.ok();
}

期望生成的OpenAPI文档中，userId和roleIds都应该作为查询参数出现。然而实际生成的文档中，roleIds被错误地生成为application/json格式的请求体参数，而不是预期的查询参数。

问题分析

这个问题涉及到SpringDoc OpenAPI的几个核心机制：

1. 参数推断机制：SpringDoc会根据方法参数上的注解自动推断参数应该出现在什么位置（查询参数、路径参数、请求体等）

2. 注解优先级：当多个注解同时存在时，SpringDoc有一定的优先级规则来决定如何生成文档

3. 版本兼容性：不同版本的SpringDoc对注解组合的处理方式可能不同

在Spring Boot 2.7环境下，当@NotEmpty单独出现在集合类型参数上时，SpringDoc 1.7.0版本会错误地将其识别为请求体参数，而不是查询参数。

解决方案

经过验证，有以下几种解决方案：

1. 升级SpringDoc版本：将springdoc-openapi升级到1.8.0版本可以解决此问题

2. 显式添加@RequestParam注解：为参数添加@RequestParam注解可以强制指定其为查询参数

@PostMapping("/bindUserRoles")
public Result<Void> bindUserRoles(@NotNull Long userId, 
                                 @RequestParam @NotEmpty List<Long> roleIds)

3. 使用DTO对象封装参数：将参数封装到一个DTO对象中，可以更清晰地表达参数结构

最佳实践建议

1. 对于简单的查询参数，建议始终使用@RequestParam注解明确指定参数位置，避免依赖框架的自动推断

2. 对于集合类型参数，考虑使用专门的DTO对象封装，可以提高API的清晰度和可维护性

3. 保持SpringDoc版本的更新，以获得更好的注解支持和完善的文档生成功能

总结

SpringDoc OpenAPI在参数推断方面提供了便利，但在特定注解组合下可能会出现不符合预期的行为。理解框架的推断规则，并在必要时使用显式注解，可以帮助开发者生成更准确的API文档。对于使用Spring Boot 2.x的项目，建议至少使用springdoc-openapi 1.8.0版本以获得更稳定的文档生成功能。