java - Java 中的 Swagger + Jersey 数字枚举

Question

我的 Rest API 中有一个字段(在 Jersey + Jackson + Bean Validation 中实现)，它是一组封闭的数值.例如，Employee rank，它可以是以下值之一:1,2,5,7。不，为每个值定义一个匹配的字符串不是一个选项。

我正在尝试让生成的 Swagger 文档为这些值提供一个数字枚举。我尝试了以下方法:

1. 使用以下属性定义整数:@ApiModelProperty(allowableValues = "1,2,5,7") Integer employeeRank。 Swagger-UI 没有显示任何枚举，只是在将 employeeRank 的类型更改为 String 之后。所以不幸的是，allowableValues 只能与 String 参数一起使用，我不希望我的模型是这样。 employeeRank 必须是整数。

2. 定义枚举:

   @JsonSerialize(using = BlockSize.OrderTypeSerializer.class)
   @JsonDeserialize(using = BlockSize.OrderTypeDeserializer.class)
   public enum EmployeeRank {
       ONW(1),
       TWO(2),
       FIVE(5),
       SEVEN(7)
   int rank;
   
   EmployeeRank(int rank) {
       this.rank = rank;
   }
   
   @JsonValue
   public int getRank() {
       return rank;
   }
   
   public class RankSerializer extends JsonSerializer<EmployeeRank> {
   
   
       @Override
       public void serialize(EmployeeRank rank, JsonGenerator generator, SerializerProvider serializerProvider) throws IOException, JsonProcessingException {
           generator.writeStartObject();
           generator.writeFieldName("rank");
           generator.writeNumber(rank.getRank());
           generator.writeEndObject();
       }
   }
   
   public class RankDeserializer extends JsonDeserializer<EmployeeRank> {
   
       @Override
       public EmployeeRank deserialize(JsonParser jsonParser, DeserializationContext deserializationContext) throws IOException, JsonProcessingException {
           int val =jsonParser.getValueAsInt();
           if (val == 1) {
               return ONE;
           }
   
           if (val == 2) {
               return TWO;
           }
   
           if (val == 5) {
               return FIVE;
           }
   
           if (val == 7) {
               return SEVEN;
           }
   
           throw new IOException("Illiegal rank value " + val);
       }
   } 
   

运气不好。 Swagger-UI 将枚举呈现为枚举名称(ONE、TWO、FIVE、SEVEN)

1. 重写 EmployeeRank 上的 toString 以将排名数字作为字符串返回，方法上有或没有 JsonValue 注释。没有任何作用。

使用 Swagger 在 Jersey 中定义一组数值以理解它似乎是一项非常微不足道的任务。有什么想法吗？

下面是我的资源配置:

        resourceConfig.packages(true, ResponseWrapper.class.getPackage().getName());
        resourceConfig.property(ServerProperties.BV_SEND_ERROR_IN_RESPONSE, true);
        resourceConfig.property(ServerProperties.BV_DISABLE_VALIDATE_ON_EXECUTABLE_OVERRIDE_CHECK, true);


            resourceConfig.register(ApiListingResource.class);
            resourceConfig.register(SwaggerSerializers.class);

        resourceConfig.register(EncodingFilter.class);
        resourceConfig.register(GZipEncoder.class);
        resourceConfig.register(DeflateEncoder.class);
        resourceConfig.register(JacksonFeature.class);
        resourceConfig.register(MultiPartFeature.class);
        resourceConfig.register(ValidationConfigurationContextResolver.class);

还有我的 Swagger 初始化程序:

 BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("3.0");
        beanConfig.setSchemes(new String[]{"https"});
        beanConfig.setHost("localhost");
        beanConfig.setBasePath("/api");
        beanConfig.setPrettyPrint(true);
        beanConfig.setResourcePackage(ApiLevel.class.getPackage().getName());
        beanConfig.setScan(true);

更新

在@fehguy 的建议下，我升级到了Jackson 2.7。并且有一些进展。请考虑以下枚举:

public enum Status {
        @JsonProperty("hello")
        ENUM1,
        @JsonProperty("world")
        ENUM2;
    }

运行以下主要应用程序:

public static void main(String[] args) throws JsonProcessingException {
        ObjectMapper mapper = new ObjectMapper();
        Status user = Status.ENUM1;

        System.out.println(mapper.writeValueAsString(user));
    }

输出是“hello”，这正是我所需要的。

但是，Swagger-UI 仍然显示枚举值。也许它不处理枚举值的 JsonProperty 注释？

Answer 1

这是一个 Jackson 配置问题。看一下在 2.6.2 或更高版本中使用 @JsonProperty 注释，它可以让您设置枚举的友好名称。