Swagger 2.0请求头枚举参数未校验且默认值不生效问题

我正在开发一个用Swagger 2.0生成API接口并落地生产代码的项目，现在碰到请求头参数的问题，想要实现两个效果：

• 传入值不符合枚举范围时抛出错误
• 未传参时自动使用默认值English

我的Swagger配置如下：

parameters:
  language:
    in: header
    name: language
    description: language the request will be processed in
    type: string
    default: English
    enum: [English, Spanish, German, French]
    required: false

但实际运行时API会接受任意值，而且默认值也没生效。生成的代码里没体现枚举约束，只标注了默认值，集成测试时默认值完全不起作用，生成的代码片段如下：

@ApiParam(value = "language the request will be processed in" , defaultValue="English") @RequestHeader(value="language", required=false) String language);

我在Stack Overflow上找到过类似问题但没得到有效解答：Swagger不校验枚举查询参数

解决方法 #

1. 实现枚举校验 #

Swagger Codegen默认不会自动生成枚举校验逻辑，可通过以下两种方式补充：

• 自定义枚举类
  先定义语言枚举：

  public enum LanguageEnum {
      English, Spanish, German, French
  }
  

  把接口参数类型从String改为LanguageEnum，Spring MVC会自动校验传入值是否在枚举范围内，不合法时抛出MethodArgumentTypeMismatchException，可通过全局异常处理器捕获后返回标准化错误响应。

• 使用JSR-380校验注解
  若不想用枚举类，给参数添加@Pattern注解限定取值范围：

  @ApiParam(value = "language the request will be processed in", defaultValue = "English")
  @RequestHeader(value = "language", required = false)
  @Pattern(regexp = "^(English|Spanish|German|French)$", message = "语言参数只能是English/Spanish/German/French中的一种")
  String language
  

  需确保项目引入JSR-380依赖（如spring-boot-starter-validation），并在启动类或配置类上添加@Validated注解开启方法级校验。

2. 让默认值生效 #

Swagger的default字段仅为文档标注，生成的@RequestHeader注解不会自动填充默认值，可通过以下方式处理：

• 在注解中指定默认值
  修改@RequestHeader注解，添加defaultValue属性：

  @ApiParam(value = "language the request will be processed in", defaultValue = "English")
  @RequestHeader(value = "language", required = false, defaultValue = "English")
  String language
  

• 方法内部手动赋值
  若参数为null，在方法逻辑里手动设置默认值：

  public ResponseEntity<?> yourApiMethod(@RequestHeader(value = "language", required = false) String language) {
      if (language == null) {
          language = "English";
      }
      // 后续业务逻辑
  }
  

额外提示：修改Swagger Codegen配置（可选） #

如果想让生成的代码自动带上校验逻辑，可在Codegen配置中开启相关选项。比如使用Maven插件时，在swagger-codegen-maven-plugin的configOptions里添加：

<configOptions>
    <enableJavaAnnotationValidation>true</enableJavaAnnotationValidation>
</configOptions>

不同版本的Codegen支持程度可能有差异，需测试验证。

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