Swagger3 GET请求使用对象接收 Query 参数，注解怎么写？

问题描述

从 Swagger2 迁移到 Swagger3，遇到一个问题：Swagger3 如何处理 GET 请求的对象参数？

在 Swagger2 中，接口上不需要添加额外的 Swagger 注解，参数类添加 @ApiModel 注解，参数类的字段添加 @ApiModelProperty 注解即可。

//Swagger2
@GetMapping("/page")
@ApiOperation("员工分页查询")
public Result<PageResult> page(EmployeePageQueryDTO employeePageQueryDTO) {
    PageResult pageResult = employeeService.pageQuery(employeePageQueryDTO);
    return Result.success(pageResult);
}

迁移到 Swagger3 后，注解发生了变化，参考对照表修改了注解：

@Api → @Tag
@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiParam → @Parameter
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

//Swagger3
@GetMapping("/page")
@Operation(summary = "部门分页查询")
public Result<PageResult> page(DeptPageQuery deptPageQuery) {
    PageResult pageResult = deptService.pageQuery(deptPageQuery);
    return Result.success(pageResult);
}

但是这样写实际展示效果不符合预期，查询参数展示成了一个 Object：

期望效果是：

解决方案

一路搜寻到了 Swagger API 的 Github：https://github.com/swagger-api/swagger-core/issues/4177

很简单，请求方法参数上加 @ParameterObject 注解

@GetMapping("/page")
@Operation(summary = "部门分页查询")
public Result<PageResult> page(@ParameterObject DeptPageQuery deptPageQuery) {
    PageResult pageResult = deptService.pageQuery(deptPageQuery);
    return Result.success(pageResult);
}

但注意这个是 springdoc-openapi-common 包下的注解，不是 swagger-annotations 包内的