Spring Boot 2中如何将参数对象字段在Swagger中单独作为参数展示

要让Swagger把QueryParametersDto的每个字段都解析为独立的查询参数，只需按以下操作处理：

1. 给DTO参数添加@ParameterObject注解 #

在接口方法的DTO参数上标注@ParameterObject，告诉Swagger将对象的字段拆分为单独的请求参数：

@GetMapping(path = "/date", produces = MediaType.APPLICATION_JSON_VALUE)
@Operation(summary = "Blah blah.")
public ResponseDto getTacreps(
    @Valid @ParameterObject QueryParametersDto queryParametersDto) {
    // 方法逻辑
}

2. 优化DTO字段的文档注解（可选） #

如果需要自定义Swagger中显示的参数名、描述信息，可以给DTO字段搭配@Parameter注解，结合已有的校验注解，让接口文档更直观：

@Value
@NoArgsConstructor(force = true)
public class QueryParametersDto {

    @Parameter(name = USER_SELECTED_AUTHORITIES, description = "用户选择的权限标识")
    @NotBlank
    private final String userSelectedAuthorities;

    @Parameter(name = JUSTIFICATION, description = "操作理由，长度限制1-4000字符")
    @NotBlank
    @Size(min = 1, max = 4000)
    private final String justification;
    // 其他字段...
}

补充说明 #

• 若使用的是springdoc-openapi（适配Spring Boot 2的主流Swagger实现），@ParameterObject来自org.springdoc.api.annotations.ParameterObject包。
• 若仍在使用旧版springfox-swagger2，则需要在方法上标注@ApiImplicitParams，并给每个字段手动添加@ApiImplicitParam，但这种方式代码冗余，更推荐迁移到springdoc。

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