swagger2 枚举属性在api文档中展示实现

场景

在请求或者返回参数的对象中，会出现一些属性对应提枚举类型，比如：状态、优先级等等。
如果在@ApiModelProperty里编号，会出现少写漏写等情况，这样api文档信息就不全面。

解决办法

动态的获取枚举类型信息，通过拦截生成swagger doc的过程，在这个过程判断字段是否是枚举字段，遍历完后设置到description中

定义拦截方法

对数值和枚举做替换

@Component
@Primary
@Slf4j
public class SwaggerDisplayConfig implements ModelPropertyBuilderPlugin {
    
    
    /**
     * 是否允许swagger
     */
    @Value("${swagger.enable:true}")
    private Boolean enableSwagger;

    @Override
    public void apply(ModelPropertyContext context) {
    
    
        //如果不支持swagger的话，直接返回
        if (!enableSwagger) {
    
    
            return;
        }

        //获取当前字段的类型
        final Class fieldType = context.getBeanPropertyDefinition().get().getField().getRawType();


        //为枚举字段设置注释
        descForEnumFields(context, fieldType);
    }

    /**
     * 为枚举字段设置注释
     */
    private void descForEnumFields(ModelPropertyContext context, Class fieldType) {
    
    
        Optional<ApiModelProperty> annotation = Optional.absent();

        if (context.getAnnotatedElement().isPresent()) {
    
    
            annotation = annotation
                    .or(ApiModelProperties.findApiModePropertyAnnotation(context.getAnnotatedElement().get()));
        }
        if (context.getBeanPropertyDefinition().isPresent()) {
    
    
            annotation = annotation.or(Annotations.findPropertyAnnotation(
                    context.getBeanPropertyDefinition().get(),
                    ApiModelProperty.class));
        }

        //没有@ApiModelProperty 或者 notes 属性没有值，直接返回
        if (!annotation.isPresent() || StringUtils.isBlank((annotation.get()).notes())) {
    
    
            return;
        }

        //@ApiModelProperties中的notes指定的class类型
        Class rawPrimaryType;
        try {
    
    
            rawPrimaryType = Class.forName((annotation.get()).notes());
        } catch (ClassNotFoundException e) {
    
    
            //如果指定的类型无法转化，直接忽略
            return;
        }

        //如果对应的class是一个@SwaggerDisplayEnum修饰的枚举类，获取其中的枚举值
        Object[] subItemRecords = null;
        SwaggerDisplayEnum swaggerDisplayEnum = AnnotationUtils
                .findAnnotation(rawPrimaryType, SwaggerDisplayEnum.class);
        if (null != swaggerDisplayEnum && Enum.class.isAssignableFrom(rawPrimaryType)) {
    
    
            subItemRecords = rawPrimaryType.getEnumConstants();
        }
        if (null == subItemRecords) {
    
    
            return;
        }


        final List<String> displayValues = Arrays.stream(subItemRecords).filter(Objects::nonNull).map(item -> {
    
    
            return item.toString() ;
        }).filter(Objects::nonNull).collect(Collectors.toList());

        String joinText = " (" + String.join("; ", displayValues) + ")";
        try {
    
    
            Field mField = ModelPropertyBuilder.class.getDeclaredField("description");
            mField.setAccessible(true);
            joinText = mField.get(context.getBuilder()) + joinText;
        } catch (Exception e) {
    
    
            log.error(e.getMessage());
        }

        final ResolvedType resolvedType = context.getResolver().resolve(fieldType);
        context.getBuilder().description(joinText).type(resolvedType);
    }



    @Override
    public boolean supports(DocumentationType documentationType) {
    
    
        return true;
    }

}

定义注解

指明需要显示在swagger上的枚举

@Target({
    
    ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerDisplayEnum {
    
    

    String valueName() default "value";

    String descName() default "desc";

}

自定义枚举类型

@SwaggerDisplayEnum()
public enum CodedEnum {
    
    

    START(1, "启用"),
    END(2, "停用");
    private Integer code;
    private String desc;

    CodedEnum(Integer code, String desc) {
    
    
        this.code = code;
        this.desc = desc;
    }

    @Override
    public String toString() {
    
    
        return String.valueOf(code) + ":" + desc;
    }
}

实体类中应用

在对应属性上的@ApiModelProperty中，notes写明对应的枚举类的路径

@Data
@ApiModel()
public class Stu {
    
    
    @ApiModelProperty("编号")
    private String id;
    @ApiModelProperty("名称")
    private String name;
    @ApiModelProperty(value = "状态",notes = "com.ferryc.enums.CodedEnum" )
    private Integer state;
}

实现效果