swagger 动态显示枚举内容 + 数值类型空指针异常统一控制

遇到的问题:

1. 当咱们定义接口的入参或者返回值的字段想把他关联的枚举内容显示到swagger的页面上方便前端同窗查看，可是又不想在每次修改枚举值的时候去手动修改description,若是不去手动修改又会遇到先后端掌握的枚举值不一致的状况
2. 定义的接口参数Integer、Boolean 字段的时候，若是不去设置该值的example的时候，获取swagger页面的时候，会提示nullpointException

解决方法:

问题1:拦截生成swagger doc的过程，在这个过程判断字段是不是枚举字段，遍历完后设置到description中
问题2：拦截生成swagger doc过程，若是是数值字段或者Boolean，设置默认的example

show 代码

• 定义拦截方法，对数值和枚举作替换

import com.fasterxml.classmate.ResolvedType;
import com.google.common.base.Optional;
import io.swagger.annotations.ApiModelProperty;
import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.stream.Collectors;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Primary;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ModelPropertyBuilder;
import springfox.documentation.schema.Annotations;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.schema.ModelPropertyBuilderPlugin;
import springfox.documentation.spi.schema.contexts.ModelPropertyContext;
import springfox.documentation.swagger.schema.ApiModelProperties;

/**
 * 对swagger展现进行修改 1. 数字、Boolean属性设置默认的example 2. 支持将枚举变量的描述按照枚举类定义展现
 *
 * @see SwaggerDisplayEnum
 * @see ApiModelProperty
 */
@Component
@Primary
@Slf4j
public class SwaggerDisplayConfig implements ModelPropertyBuilderPlugin {

    /**
     * 是否容许swagger
     */
    @Value("${swagger.enable:false}")
    private Boolean enableSwagger;

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

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

        //设置对数字的字段设置默认的example
        setDefaultExample(context, fieldType);

        //为枚举字段设置注释
        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;
        }

        //从annotation中获取对应的值和描述的变量名
        String valueName = swaggerDisplayEnum.valueName();
        String descName = swaggerDisplayEnum.descName();
        if (StringUtils.isBlank(valueName) || StringUtils.isBlank(descName)) {
            return;
        }

        final List<String> displayValues = Arrays.stream(subItemRecords).filter(Objects::nonNull).map(item -> {
            Class currentClass = item.getClass();

            String value;
            String desc;
            try {
                Field valueField = currentClass.getField(valueName);
                Field descField = currentClass.getField(descName);
                valueField.setAccessible(true);
                descField.setAccessible(true);
                value = valueField.get(item).toString();
                desc = descField.get(item).toString();
            } catch (NoSuchFieldException | IllegalAccessException e) {
                log.warn("获取枚举的属性和值失败, {}", e.getMessage());
                return null;
            }
            return value + ":" + desc;
        }).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);
    }

    /**
     * 设置默认的example
     */
    private void setDefaultExample(ModelPropertyContext context, Class fieldType) {
        if (Number.class.isAssignableFrom(fieldType)) {
            context.getBuilder().example("1");
        }
        if (Boolean.class.isAssignableFrom(fieldType)) {
            context.getBuilder().example("true");
        }
    }

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

复制代码

• 定义用来判断是否须要显示枚举到swagger上的annotation

/**
 * 须要swagger展现的枚举
 * 默认 支持 枚举中属性名为 value和desc
 * 若是不是，请设置valueName和descName
 *
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerDisplayEnum {

    String valueName() default "value";
    String descName() default "desc";

}
复制代码

• 在定义出入参bean的时候，在想要显示枚举详情的字段上@ApiModelProperties属性中指定该字段对应的枚举类

@Data
@ApiModel("返回值bean")
public class ResultBean {

....
/**
 * 枚举字段
 */
@ApiModelProperty(value = "须要显示的枚举值", notes = "com.li.test.enums.AAEnum")
private Integer aa;
...

}

复制代码

完成上面的操做，aa对应的枚举类AAEnum的值和意思都能在swagger字段的description中显示出来了。