Spring Boot中如何通过Swagger为路径变量指定可选枚举值？

没问题，这事儿我熟！刚好在Spring Boot里结合SpringFox（Swagger 2）给路径变量加枚举约束是很常见的需求，我给你一步步拆解清楚怎么实现～

首先你可以先定义一个枚举类，把允许的可选值都放进去：

public enum ProviderType {
    AWS, AZURE, GCP, ALIBABA
}

然后在控制器的路径变量里直接用这个枚举类型，Spring会自动校验传入的值是否在枚举范围内，如果是不在列表里的非法值，会直接返回400错误：

@RestController
@RequestMapping("/api/providers")
public class ProviderController {

    @GetMapping("/{provider}")
    public ResponseEntity<String> getProviderDetails(@PathVariable ProviderType provider) {
        // 这里写你的业务逻辑就行
        return ResponseEntity.ok("Details for provider: " + provider.name());
    }
}

接下来是让Swagger文档里明确展示这些可选值，虽然SpringFox官方文档没专门大篇幅讲，但其实有几种实用方式：

方式1：用@ApiImplicitParam指定允许值 #

如果不想用Java枚举类，只想用String类型的路径变量，可以在控制器方法上加上@ApiImplicitParam，通过allowableValues属性指定可选值，Swagger文档里会直接显示下拉选项：

@RestController
@RequestMapping("/api/providers")
public class ProviderController {

    @GetMapping("/{provider}")
    @ApiImplicitParam(
        name = "provider",
        value = "Cloud provider type",
        allowableValues = "AWS, AZURE, GCP, ALIBABA",
        paramType = "path"
    )
    public ResponseEntity<String> getProviderDetails(@PathVariable String provider) {
        // 这里需要自己手动校验值是否合法
        if (!Arrays.asList("AWS", "AZURE", "GCP", "ALIBABA").contains(provider)) {
            return ResponseEntity.badRequest().body("Invalid provider type! Allowed values: AWS, AZURE, GCP, ALIBABA");
        }
        return ResponseEntity.ok("Details for provider: " + provider);
    }
}

方式2：让Swagger自动识别枚举类 #

如果用的是Java枚举类作为路径变量，想让Swagger自动识别并展示枚举选项，可以配置Swagger的Docket，同时给枚举类加注解增强文档说明：

首先给枚举类加上Swagger注解：

@ApiModel(description = "Allowed cloud provider types")
public enum ProviderType {
    @ApiModelProperty("Amazon Web Services")
    AWS,
    @ApiModelProperty("Microsoft Azure")
    AZURE,
    @ApiModelProperty("Google Cloud Platform")
    GCP,
    @ApiModelProperty("Alibaba Cloud")
    ALIBABA
}

然后在Swagger配置类里做一下扩展：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage.controller")) // 替换成你的控制器包路径
                .paths(PathSelectors.any())
                .build()
                .directModelSubstitute(ProviderType.class, String.class); // 告诉Swagger把枚举转成字符串展示
    }
}

这样配置后，Swagger文档里的路径变量会自动列出所有枚举可选值，还会显示每个值的描述信息。

如果用的是Spring Validation，还可以给String类型的路径变量加@Pattern注解，既做参数校验又能让Swagger识别规则：

@GetMapping("/{provider}")
public ResponseEntity<String> getProviderDetails(
    @PathVariable 
    @Pattern(regexp = "^(AWS|AZURE|GCP|ALIBABA)$", message = "Invalid provider type. Allowed values: AWS, AZURE, GCP, ALIBABA") 
    String provider
) {
    // 业务逻辑
    return ResponseEntity.ok("Details for provider: " + provider);
}

这种方式会在参数非法时返回带自定义错误信息的400响应，部分Swagger版本还会自动把正则里的可选值展示在文档里。

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