Java Swagger 2中如何为枚举生成可复用的引用？

问题背景 #

在集成Swagger 2的Dropwizard应用中，含枚举属性的对象生成的swagger.json会将枚举内联输出：

{"swagger":"2.0","definitions":{"Thing":{"type":"object","properties":{"color":{"type":"string","enum":["BLUE","GREEN","RED","YELLOW"]}}}}}

期望将枚举Color转为可复用的独立定义，输出如下：

{"swagger":"2.0","definitions":{"Color":{"type":"string","enum":["BLUE","GREEN","RED","YELLOW"]},"Thing":{"type":"object","properties":{"color":{"$ref":"#/definitions/Color"}}}}}

已知OpenAPI 3可通过@Schema(enumAsRef = true)注解实现该效果，现询问Swagger 2的可行方案及是否需要迁移至OpenAPI 3。

答案 #

Swagger 2的实现方式 #

Swagger 2没有原生支持类似enumAsRef = true的注解，但可以通过以下两种方式实现枚举复用：

• 手动注册枚举模型并指定引用
  在Swagger配置类中，将枚举类注册为独立的模型定义，同时在实体类的枚举字段上通过@ApiModelProperty指定引用的枚举类型：

  // Swagger配置类示例
  @Bean
  public Docket api() {
      TypeResolver typeResolver = new TypeResolver();
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("your.app.package"))
              .paths(PathSelectors.any())
              .build()
              .additionalModels(typeResolver.resolve(Color.class)); // 注册Color为独立定义
  }
  
  // Thing实体类示例
  public class Thing {
      @ApiModelProperty(dataType = "Color") // 指定引用已注册的Color定义
      private Color color;
  
      // getter、setter方法
  }
  

• 社区扩展辅助实现
  部分第三方扩展可以自动将枚举转为引用形式，但需要额外引入依赖并配置，这类扩展的维护性需自行评估。

是否需要迁移至OpenAPI 3 #

如果上述手动配置能满足需求，无需立即迁移。但从长期来看，OpenAPI 3的@Schema(enumAsRef = true)是更简洁的原生方案，同时OpenAPI 3支持更多高级特性（如组件复用、更灵活的参数校验等），若项目有升级计划，迁移至OpenAPI 3是更优选择。

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