swagger 动态显示枚举enums内容注释 只修改一次（自定义注解实现）

场景

项目使用swagger去自动生成接口文档。
当存在一个enum枚举时，会有很多vo和param的dto去引用它。
此时，如果修改这个enum，相关联的很多dto和其他文件的注释description就需要关联修改，
否则就会造成前后端掌握的枚举值不一致的情况。

针对这种问题，我参考了前辈的文章 《swagger 动态显示枚举内容 + 数值类型空指针异常统一控制》. 给出了针对enum的swagger注释只修改一次的解决方案。

一、自定义注解@SwaggerDisplayEnum

/**
 * 需要swagger展示的枚举注释
 *
 */
@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerDisplayEnum {

	/**
	 * 所有value值，按顺序用分号【;】隔开
	 */
	String valueNames() default "默认value值";

	/**
	 * 所有descp值，按顺序用分号【;】隔开，注意对应value的顺序
	 */
	String descpNames() default "默认描述值";

}

二、生成enum的swagger描述

拦截生成swagger doc的过程，在这个过程判断字段是否是枚举字段，遍历完后设置到description中。

package com.xxx;

import com.xxx.enums.SwaggerDisplayEnum;

import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.stream.Collectors;

import org.apache.commons.lang3.StringUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.stereotype.Component;

import com.fasterxml.classmate.ResolvedType;
import com.google.common.base.Optional;

import io.swagger.annotations.ApiModelProperty;
import lombok.extern.slf4j.Slf4j;
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展示进行修改 ，支持将枚举变量的描述按照枚举类定义展示
 *
 * @see SwaggerDisplayEnum
 * @see ApiModelProperty
 */
@Component
@Primary
@Slf4j
public class SwaggerDisplayConfig implements ModelPropertyBuilderPlugin {

	@Override
	public void apply(ModelPropertyContext context) {
		// 获取当前字段的类型
		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;
		}

		// 从annotation中获取enum对应的value和描述
		String[] valueNames = swaggerDisplayEnum.valueNames().split(";");
		String[] descNames = swaggerDisplayEnum.descpNames().split(";");
		if (valueNames.length < 1 || descNames.length < 1) {
			return;
		}
		
//		循环枚举值
		final List<String> displayValues = Arrays.stream(subItemRecords).filter(Objects::nonNull).map(item -> {
			Class<?> currentClass = item.getClass();

			String value = "";
			String descp = "";
			try {
				Field valueField = null;
//				循环enum-valueNames，找到枚举当前循环的value和descp
				for (int i = 0; i < valueNames.length; i++) {
					if (item.toString().equalsIgnoreCase(valueNames[i])) {
						valueField = currentClass.getField(valueNames[i]);
						descp = descNames[i];
					}
				}
				valueField.setAccessible(true);
				value = valueField.get(item).toString();
			} catch (NoSuchFieldException | IllegalAccessException e) {
				e.printStackTrace();
				log.warn("获取枚举的属性和值失败, {}", e.getMessage());
				return null;
			}
			return value + ":" + descp;
		}).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;
	}
}

三、使用注解生成注释

枚举上加注解@SwaggerDisplayEnum，因为上面处理的过程我定义的是用分号【;】截取字符串，所以此处对应的格式也应如此， 示例：

package com.xxx.enums;

@SwaggerDisplayEnum(valueNames = "one;two;three;four", descpNames = "一;二;三;四")
public enum NumEnum {

	one(0, "一"), 
	two(1, "二"),
	three(2, "三"), 
	four(3, "四");

    NumEnum (int code, String descp) {
        this.code = code;
        this.descp = descp;
    }

    private final int code;
    private final String descp;

    public int getCode() {
        return code;
    }

    public String getDescp() {
        return descp;
    }
}

四、dto使用

返回枚举时，变量上的注解@ApiModelProperty使用，value 填写变量含义，notes 应填写变量enum的路径。 示例：

@Data
public class returnVo {

	@ApiModelProperty(value = "数字枚举", notes = "com.xxx.enums.NumEnum ")
	private NumEnum num;
	
}

此时，所有步骤已完成，当controller返回这个包含自定义注解enum的vo时，前端swagger显示对应的参数说明如下（可用值是自动生成的，可用属性allowableValues自定义）：