如何通过Spring和Swagger自定义枚举列表查询参数名称？

要实现枚举列表类型的查询参数，同时自定义参数名称，你可以通过以下两种方式实现：

方式一：直接在Controller方法参数上配置 #

在Controller的请求参数上，结合@RequestParam指定自定义参数名，再用Swagger的@Parameter注解明确数组类型和元信息：

@GetMapping("/receipts")
public List<Receipt> getReceipts(
    @RequestParam(name = "status")
    @Parameter(description = "Status of the receipt", example = "paid", schema = @Schema(type = "array", implementation = ReceiptStatus.class))
    List<ReceiptStatus> statuses
) {
    // 业务逻辑实现
    return receiptService.findByStatuses(statuses);
}

方式二：通过DTO封装查询参数 #

如果用DTO类统一管理查询参数，可在DTO属性上结合@JsonProperty指定参数名，同时用@Schema明确数组类型：

public class ReceiptQueryDTO {
    @JsonProperty("status")
    @Schema(description = "Status of the receipt", example = "paid", type = "array", implementation = ReceiptStatus.class)
    private List<ReceiptStatus> statuses;

    // getter/setter方法
}

然后在Controller中使用该DTO：

@GetMapping("/receipts")
public List<Receipt> getReceipts(ReceiptQueryDTO queryDTO) {
    // 业务逻辑实现
    return receiptService.findByQueryDTO(queryDTO);
}

关于之前尝试的问题说明 #

• 示例1中@ArraySchema的name属性仅用于定义Schema本身的名称，不会覆盖查询参数的实际名称，参数名默认取Java属性名statuses
• 示例2直接用@Schema标注List属性时，Swagger会错误将其解析为字符串类型，而非数组类型

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