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

2021年9月17日 10点热度 0条评论 来源: sgambler

场景

项目使用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自定义):

参数名称 参数说明
num 数字枚举 (one:一; two:二; three:三; four:四),可用值:one;two;three;four
    原文作者:sgambler
    原文地址: https://blog.csdn.net/sgambler/article/details/103524840
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系管理员进行删除。