如何为Swagger中的GET/Users接口添加查询筛选器？

1. 修正控制器参数绑定注解 #

你当前用@RequestParam绑定自定义Filter类是错误的，@RequestParam仅适用于单个查询参数，绑定自定义对象需要使用@ModelAttribute（或省略注解，Spring MVC会默认按模型属性处理）。修改控制器方法参数：

@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Success"),
        @ApiResponse(responseCode = "400", description = "Client error"),
        @ApiResponse(responseCode = "500", description = "Server error")
})
@GetMapping("/Users")
public ResponseEntity<PagingDto<UserResource>> getUsers(HttpServletRequest request,
                                                        @Min(1)
                                                        @RequestParam(required = false) Integer startIndex,
                                                        @RequestParam(required = false) Integer count,
                                                        @ModelAttribute(required = false) Filter filter) {
    final PagingDto<UserResource> users = userService.getUsers(startIndex, count, filter);
    return new ResponseEntity<>(users, HttpStatus.OK);
}

2. 完善Filter类配置 #

确保Filter类包含getter和setter方法（Spring需通过这些方法注入查询参数），同时添加Swagger注解让页面正确展示每个字段，而非单独的filter参数：

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "用户查询筛选条件")
public class Filter {
    @ApiModelProperty(value = "用户名", example = "jack")
    private String username;
    
    @ApiModelProperty(value = "最大结果数", example = "10")
    private Integer maxResult;
    
    @ApiModelProperty(value = "是否支持", example = "true")
    private Boolean supported;

    // 必须添加getter和setter
    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public Integer getMaxResult() {
        return maxResult;
    }

    public void setMaxResult(Integer maxResult) {
        this.maxResult = maxResult;
    }

    public Boolean getSupported() {
        return supported;
    }

    public void setSupported(Boolean supported) {
        this.supported = supported;
    }
}

3. 更新Service层方法，实现过滤逻辑 #

修改getUsers方法签名接收Filter参数，并在业务逻辑中加入筛选条件：

@Override
public PagingDto<UserResource> getUsers(Integer startIndex, Integer count, Filter filter) {
    // 构建动态查询条件
    Specification<User> spec = (root, query, cb) -> {
        List<Predicate> predicates = new ArrayList<>();
        if (filter != null && filter.getUsername() != null) {
            predicates.add(cb.like(root.get("username"), "%" + filter.getUsername() + "%"));
        }
        if (filter != null && filter.getSupported() != null) {
            predicates.add(cb.equal(root.get("supported"), filter.getSupported()));
        }
        return cb.and(predicates.toArray(new Predicate[0]));
    };

    // 执行分页查询（根据实际Repository方法调整）
    Page<User> userPage = userRepository.findAll(spec, PageRequest.of(
            startIndex != null ? startIndex - 1 : 0,
            count != null ? count : 10
    ));

    // 转换为UserResource并封装分页结果
    PagingDto<UserResource> pagingDto = new PagingDto<>();
    pagingDto.setItems(userPage.getContent().stream()
            .map(this::convertToUserResource)
            .collect(Collectors.toList()));
    pagingDto.setTotal(userPage.getTotalElements());
    return pagingDto;
}

4. 验证效果 #

重启服务后，Swagger页面会展示username、maxResult、supported三个独立的查询参数，可直接输入值进行过滤测试，参数会自动绑定到Filter对象并参与业务逻辑筛选。

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