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

news2025/1/11 14:08:16

简中互联网上就没一个靠谱的答案，最终翻到了 Github Issue 上才解决，真 TMD…… CSDN 就一坨 shit mountain

解决方案

原文：https://github.com/swagger-api/swagger-core/issues/4177

太长不看：
请求方法参数上加 @ParameterObject 注解

    @GetMapping("/list")
    @Operation(summary = "会议列表")
    public Response<List<ScheduleListItemVo>> listMeetings(@ParameterObject ListScheduleForm form)

问题描述

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

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

@GetMapping("/list")
@ApiOperation("会议列表")
public Response<List<ScheduleListItemVo>> listMeetings(ListScheduleForm form)

@Data
@ApiModel("查询语言记录列表参数")
public class ListScheduleForm {

    /**
     * 查询的会议时间类型：1-未来会议、2-历史会议
     */
    @NotNull
    @ApiModelProperty("查询的会议时间类型：1-未来会议、2-历史会议")
    private Integer timeType = 1;

    /**
     * 查询页码
     */
    @ApiModelProperty("查询页码")
    private Integer page = 1;

    /**
     * 分页查询条数
     */
    @ApiModelProperty("分页查询条数")
    private Integer size = 20;

}

迁移到 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")

@GetMapping("/list")
@Operation(summary = "会议列表")
public Response<List<ScheduleListItemVo>> listMeetings(ListScheduleForm form)

@Data
@Schema(description = "查询语言记录列表参数")
public class ListScheduleForm {

    /**
     * 查询的会议时间类型：1-未来会议、2-历史会议
     */
    @NotNull
    @Schema(description = "查询的会议时间类型：1-未来会议、2-历史会议")
    private Integer timeType;

    /**
     * 查询页码
     */
    @Schema(description = "查询页码")
    private Integer page = 1;

    /**
     * 分页查询条数
     */
    @Schema(description = "分页查询条数")
    private Integer size = 20;

}

实际展示效果不符合预期，查询参数展示成了一个 Object：
在这里插入图片描述

期望效果是：
在这里插入图片描述

解决方案

一路搜寻到了 Swagger API 的 Github：https://github.com/swagger-api/swagger-core/issues/4177
很简单，请求方法参数上加 @ParameterObject 注解

    @GetMapping("/list")
    @Operation(summary = "会议列表")
    public Response<List<ScheduleListItemVo>> listMeetings(@ParameterObject ListScheduleForm form)