Knife4j中@ParameterObject注解解决查询参数格式问题

在Spring Boot应用开发中，Knife4j作为Swagger的增强工具，为API文档提供了更友好的界面和功能。本文将介绍一个在使用Knife4j时遇到的常见问题及其解决方案。

问题背景

在Spring Boot 3.2.4项目中，当使用Knife4j 4.4.0和springdoc-openapi 2.4.0时，开发者遇到了一个关于查询参数格式的问题。具体表现为：

1. 定义了一个查询参数对象（如SystemRoleQO），继承自分页基类（BasePageQuery）
2. 在Controller方法中使用@Parameter、@ModelAttribute和@Valid注解标记该参数
3. 在Swagger UI中显示正常，参数被正确展开为单独字段
4. 但在Knife4j界面中，参数被显示为一个整体对象，而不是展开的单独参数

问题分析

这个问题源于Knife4j对参数处理的机制与原生Swagger有所不同。当使用@ModelAttribute注解时，Knife4j默认会将整个对象作为一个参数处理，而不是自动展开其内部属性。

这种情况在需要分页查询的场景中尤为常见，因为通常会定义一个包含分页参数和业务查询条件的复合对象。如果参数不能被正确展开，会导致前端调用时参数格式不正确，影响接口的正常使用。

解决方案

通过添加@ParameterObject注解可以完美解决这个问题。这个注解的作用是告诉Knife4j应该将对象参数展开为其属性字段。

示例代码如下：

@Operation(description = "列表")
@GetMapping("list")
public PageInfo<SystemConfigVO> list(
    @Parameter(name = "列表查询对象", in = ParameterIn.QUERY) 
    @ParameterObject 
    @ModelAttribute 
    @Valid 
    SystemConfigQO systemConfigQO) {
    return PageInfo.pageVoCovert(systemConfigService.selectAll(systemConfigQO), SystemConfigVO.class);
}

实际应用

在实际项目中，这种解决方案可以应用于各种需要组合查询条件的场景，例如：

1. 分页查询（包含页码、页大小等参数）
2. 条件筛选（包含多个筛选字段）
3. 排序查询（包含排序字段和排序方式）

对于POST请求同时包含请求体和查询参数的情况，也可以同样适用：

@Operation(summary = "查询新闻列表-基于各种条件")
@PostMapping("/news/search")
public ResponseInfo<TableDateInfo<NewsSingleVo>> getNewsListBySearch(
        @RequestBody @Validated NewsListBySearchAdjustDto dto,
        @ParameterObject @ModelAttribute @Validated PageQuery pagequery) {
    // 方法实现
}

总结

在Knife4j中使用@ParameterObject注解可以很好地解决查询参数对象展开的问题，使得API文档更加清晰易用。这是Knife4j提供的一个实用特性，特别适合处理复杂的查询参数场景。开发者在使用Knife4j时，如果遇到类似问题，可以考虑使用这个注解来优化API文档的展示效果。