perf(enum): Added the 'enumConvertor' configuration and modified the enumeration example value logic

src/main/java/com/ly/doc/handler/IHeaderHandler.java

@@ -140,7 +140,8 @@ default void handleParamTypeAndValue(JavaParameter javaParameter, ApiReqParam ap
 				apiReqHeader.setDesc(apiReqHeader.getDesc() + enumComment);
 				apiReqHeader.setType(ParamTypeConstants.PARAM_TYPE_ARRAY);
 
-				EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(gicJavaClass, builder);
+				EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(gicJavaClass, builder,
+						Boolean.FALSE);
 				if (Objects.nonNull(enumInfoAndValue)) {
 					String enumValue = StringUtil.removeDoubleQuotes(String.valueOf(enumInfoAndValue.getValue()));
 					apiReqHeader.setValue(enumValue + "," + enumValue).setEnumInfoAndValues(enumInfoAndValue);
@@ -173,7 +174,7 @@ else if (javaClass.isEnum()) {
 			apiReqHeader.setDesc(apiReqHeader.getDesc() + enumComment);
 			apiReqHeader.setType(ParamTypeConstants.PARAM_TYPE_ENUM);
 
-			EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(javaClass, builder);
+			EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(javaClass, builder, Boolean.FALSE);
 			if (Objects.nonNull(enumInfoAndValue)) {
 				String enumValue = StringUtil.removeDoubleQuotes(String.valueOf(enumInfoAndValue.getValue()));
 				apiReqHeader.setValue(enumValue)

src/main/java/com/ly/doc/helper/FormDataBuildHelper.java

@@ -174,7 +174,7 @@ else if (JavaClassValidateUtil.isPrimitive(subTypeName)) {
 				formDataList.add(formData);
 			}
 			else if (javaClass.isEnum()) {
-				Object value = JavaClassUtil.getEnumValue(javaClass, builder);
+				Object value = JavaClassUtil.getEnumValue(javaClass, builder, Boolean.FALSE);
 				if (tagsMap.containsKey(DocTags.MOCK) && StringUtil.isNotEmpty(tagsMap.get(DocTags.MOCK))) {
 					value = ParamUtil.formatMockValue(tagsMap.get(DocTags.MOCK));
 				}

src/main/java/com/ly/doc/helper/JsonBuildHelper.java

@@ -60,7 +60,8 @@ public static String buildReturnJson(DocJavaMethod docJavaMethod, ProjectDocConf
 			return "File download.";
 		}
 		if (method.getReturns().isEnum() && Objects.isNull(responseBodyAdvice)) {
-			return StringUtil.removeQuotes(String.valueOf(JavaClassUtil.getEnumValue(method.getReturns(), builder)));
+			return StringUtil
+				.removeQuotes(String.valueOf(JavaClassUtil.getEnumValue(method.getReturns(), builder, Boolean.TRUE)));
 		}
 		if (method.getReturns().isPrimitive() && Objects.isNull(responseBodyAdvice)) {
 			String typeName = method.getReturnType().getCanonicalName();
@@ -157,7 +158,8 @@ public static String buildJson(String typeName, String genericCanonicalName, boo
 
 		// Handle enum types
 		if (javaClass.isEnum()) {
-			return StringUtil.removeQuotes(String.valueOf(JavaClassUtil.getEnumValue(javaClass, projectBuilder)));
+			return StringUtil
+				.removeQuotes(String.valueOf(JavaClassUtil.getEnumValue(javaClass, projectBuilder, Boolean.TRUE)));
 		}
 
 		StringBuilder result = new StringBuilder();
@@ -387,7 +389,8 @@ else if (gicName.length() == 1) {
 								JavaClass arraySubClass = projectBuilder.getJavaProjectBuilder()
 									.getClassByName(gicName);
 								if (arraySubClass.isEnum()) {
-									Object value = JavaClassUtil.getEnumValue(arraySubClass, projectBuilder);
+									Object value = JavaClassUtil.getEnumValue(arraySubClass, projectBuilder,
+											Boolean.TRUE);
 									result.append("[").append(value).append("],");
 									continue;
 								}
@@ -460,15 +463,15 @@ else if (typeName.equals(fieldGicName)) {
 							// if has Annotation @JsonSerialize And using
 							// ToStringSerializer && isResp
 							else if (toStringSerializer && isResp) {
-								Object value = JavaClassUtil.getEnumValue(javaClass, projectBuilder);
+								Object value = JavaClassUtil.getEnumValue(javaClass, projectBuilder, Boolean.TRUE);
 								result.append(value).append(",");
 							}
 							// if has @JsonFormat
 							else if (StringUtil.isNotEmpty(fieldJsonFormatValue)) {
 								result.append(fieldJsonFormatValue).append(",");
 							}
 							else {
-								Object value = JavaClassUtil.getEnumValue(javaClass, projectBuilder);
+								Object value = JavaClassUtil.getEnumValue(javaClass, projectBuilder, Boolean.TRUE);
 								result.append(value).append(",");
 							}
 						}

src/main/java/com/ly/doc/helper/ParamsBuildHelper.java

@@ -505,7 +505,7 @@ else if (JavaClassValidateUtil.isCollection(subTypeName)
 								param.setType(ParamTypeConstants.PARAM_TYPE_ARRAY);
 
 								EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(arraySubClass,
-										projectBuilder);
+										projectBuilder, Boolean.TRUE);
 								if (Objects.nonNull(enumInfoAndValue)) {
 									param.setValue("[" + enumInfoAndValue.getValue() + "]")
 										.setEnumInfoAndValues(enumInfoAndValue);

src/main/java/com/ly/doc/model/ApiConfig.java

@@ -458,11 +458,14 @@ public class ApiConfig {
 	private boolean addDefaultHttpStatuses;
 
 	/**
-	 * Show enum name for example
+	 * Whether to enable the enumeration converter, The default value is false. If true,
+	 * the enumeration value is parsed as an enumeration example value in the
+	 * header/path/query request mode. If false, take the enumeration name as the
+	 * enumeration example value
 	 *
 	 * @since 3.1.0
 	 */
-	private boolean enumNameExample = Boolean.FALSE;
+	private boolean enumConvertor = Boolean.FALSE;
 
 	public static ApiConfig getInstance() {
 		return instance;
@@ -1145,12 +1148,12 @@ public void setAddDefaultHttpStatuses(boolean addDefaultHttpStatuses) {
 		this.addDefaultHttpStatuses = addDefaultHttpStatuses;
 	}
 
-	public boolean isEnumNameExample() {
-		return enumNameExample;
+	public boolean isEnumConvertor() {
+		return enumConvertor;
 	}
 
-	public void setEnumNameExample(boolean enumNameExample) {
-		this.enumNameExample = enumNameExample;
+	public void setEnumConvertor(boolean enumConvertor) {
+		this.enumConvertor = enumConvertor;
 	}
 
 }

src/main/java/com/ly/doc/template/IRestDocTemplate.java

@@ -1167,7 +1167,8 @@ else if (frameworkAnnotations.getRequestPartAnnotation()
 						.setQueryParam(isQueryParam)
 						.setId(paramList.size() + 1)
 						.setType(ParamTypeConstants.PARAM_TYPE_ARRAY);
-					EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(gicJavaClass, builder);
+					EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(gicJavaClass, builder,
+							Boolean.FALSE);
 					if (Objects.nonNull(enumInfoAndValue)) {
 						param.setValue(StringUtil.removeDoubleQuotes(String.valueOf(enumInfoAndValue.getValue())))
 							.setEnumInfoAndValues(enumInfoAndValue);
@@ -1275,7 +1276,8 @@ else if (javaClass.isEnum()) {
 					.setRequired(required)
 					.setVersion(DocGlobalConstants.DEFAULT_VERSION);
 
-				EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(javaClass, builder);
+				EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(javaClass, builder,
+						ApiParamEnum.BODY.equals(apiParamEnum));
 				if (Objects.nonNull(enumInfoAndValue)) {
 					param.setValue(StringUtil.removeDoubleQuotes(String.valueOf(enumInfoAndValue.getValue())))
 						.setEnumInfoAndValues(enumInfoAndValue)
@@ -1472,7 +1474,7 @@ else if (frameworkAnnotations.getPathVariableAnnotation()
 					.getAnnotationName()
 					.contains(annotationName)) {
 					if (javaClass.isEnum()) {
-						Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder);
+						Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder, Boolean.FALSE);
 						mockValue = StringUtil.removeQuotes(String.valueOf(value));
 					}
 					if (pathParamsMap.containsKey(paramName)) {
@@ -1486,7 +1488,7 @@ else if (frameworkAnnotations.getRequestParamAnnotation()
 					.getAnnotationName()
 					.contains(annotationName)) {
 					if (javaClass.isEnum()) {
-						Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder);
+						Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder, Boolean.FALSE);
 						mockValue = StringUtil.removeQuotes(String.valueOf(value));
 					}
 					if (queryParamsMap.containsKey(paramName)) {
@@ -1563,7 +1565,7 @@ else if (JavaClassValidateUtil.isArray(fullyQualifiedName)
 				String value;
 				JavaClass javaClass1 = configBuilder.getClassByName(gicName);
 				if (Objects.nonNull(javaClass1) && javaClass1.isEnum()) {
-					value = String.valueOf(JavaClassUtil.getEnumValue(javaClass1, configBuilder));
+					value = String.valueOf(JavaClassUtil.getEnumValue(javaClass1, configBuilder, Boolean.FALSE));
 				}
 				else {
 					value = RandomUtil.randomValueByType(gicName);
@@ -1581,7 +1583,7 @@ else if (JavaClassValidateUtil.isArray(fullyQualifiedName)
 			// enum type
 			else if (javaClass.isEnum()) {
 				// do nothing
-				Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder);
+				Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder, Boolean.FALSE);
 				String strVal = StringUtil.removeQuotes(String.valueOf(value));
 				FormData formData = new FormData();
 				formData.setKey(paramName);

src/main/java/com/ly/doc/template/JAXRSDocBuildTemplate.java

@@ -450,7 +450,7 @@ private ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje
 				}
 				JavaClass gicJavaClass = builder.getJavaProjectBuilder().getClassByName(gicName);
 				if (gicJavaClass.isEnum()) {
-					Object value = JavaClassUtil.getEnumValue(gicJavaClass, builder);
+					Object value = JavaClassUtil.getEnumValue(gicJavaClass, builder, Boolean.FALSE);
 					ApiParam param = ApiParam.of()
 						.setField(paramName)
 						.setDesc(comment + ",[array of enum]")
@@ -560,7 +560,7 @@ else if (JavaClassValidateUtil.isFile(typeName)) {
 			// param is enum
 			else if (javaClass.isEnum()) {
 				String o = JavaClassUtil.getEnumParams(javaClass);
-				Object value = JavaClassUtil.getEnumValue(javaClass, builder);
+				Object value = JavaClassUtil.getEnumValue(javaClass, builder, Boolean.FALSE);
 				ApiParam param = ApiParam.of()
 					.setField(paramName)
 					.setId(paramList.size() + 1)
@@ -664,7 +664,7 @@ private ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap
 							|| JakartaJaxrsAnnotations.JAXB_REST_PATH_FULLY.equals(annotationName)
 							|| JAXRSAnnotations.JAX_PATH_PARAM_FULLY.equals(annotationName)) {
 						if (javaClass.isEnum()) {
-							Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder);
+							Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder, Boolean.FALSE);
 							mockValue = StringUtil.removeQuotes(String.valueOf(value));
 						}
 						pathParamsMap.put(paramName, mockValue);
@@ -715,7 +715,7 @@ else if (JavaClassValidateUtil.isArray(fullyQualifiedName)
 					}
 					else if (javaClass.isEnum()) {
 						// do nothing
-						Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder);
+						Object value = JavaClassUtil.getEnumValue(javaClass, configBuilder, Boolean.FALSE);
 						String strVal = StringUtil.removeQuotes(String.valueOf(value));
 						FormData formData = new FormData();
 						formData.setDescription(comment);

src/main/java/com/ly/doc/utils/JavaClassUtil.java

@@ -30,6 +30,7 @@
 import com.ly.doc.constants.DocValidatorAnnotationEnum;
 import com.ly.doc.constants.JSRAnnotationConstants;
 import com.ly.doc.constants.JavaTypeConstants;
+import com.ly.doc.constants.ParamTypeConstants;
 import com.ly.doc.model.ApiConfig;
 import com.ly.doc.model.ApiDataDictionary;
 import com.ly.doc.model.DocJavaField;
@@ -56,6 +57,7 @@
 import com.thoughtworks.qdox.model.expression.TypeRef;
 import com.thoughtworks.qdox.model.impl.DefaultJavaField;
 import com.thoughtworks.qdox.model.impl.DefaultJavaParameterizedType;
+import net.datafaker.BojackHorseman;
 import org.apache.commons.lang3.StringUtils;
 
 import java.lang.reflect.Field;
@@ -351,11 +353,12 @@ public static String getSameSignatureMethodCommonFromInterface(JavaClass cls, Ja
 	 * @param javaClass The JavaClass object representing the enum class
 	 * @param builder A ProjectDocConfigBuilder object used to retrieve API configuration
 	 * and the class loader
+	 * @param jsonEnum Enum is json or not
 	 * @return Object The enum value, whose type depends on the specific enum definition
 	 * @throws RuntimeException If the enum constants do not exist
 	 */
-	public static Object getEnumValue(JavaClass javaClass, ProjectDocConfigBuilder builder) {
-		EnumInfoAndValues enumInfoAndValue = getEnumInfoAndValue(javaClass, builder);
+	public static Object getEnumValue(JavaClass javaClass, ProjectDocConfigBuilder builder, boolean jsonEnum) {
+		EnumInfoAndValues enumInfoAndValue = getEnumInfoAndValue(javaClass, builder, jsonEnum);
 		if (enumInfoAndValue == null) {
 			return null;
 		}
@@ -367,6 +370,30 @@ public static Object getEnumValue(JavaClass javaClass, ProjectDocConfigBuilder b
 	/**
 	 * Get the value of an enumConstant
 	 * <p>
+	 * First look for it using the @JsonValue annotation, and if you can't find it, look
+	 * for the default value of the enumeration field
+	 * @param javaClass The JavaClass object representing the enum class
+	 * @param builder A ProjectDocConfigBuilder object used to retrieve API configuration
+	 * and the class loader
+	 * @param enumConstant The JavaField object representing the enum constant
+	 * @return Object The enum value, whose type depends on the specific enum definition
+	 * @throws RuntimeException If the enum constants do not exist
+	 */
+	public static Object getDefaultEnumValue(JavaClass javaClass, ProjectDocConfigBuilder builder,
+			JavaField enumConstant) {
+		// Try getting value from method with JsonValue annotation
+		Object enumValue = getEnumValueWithJsonValue(javaClass, builder, enumConstant);
+		if (enumValue != null) {
+			return enumValue;
+		}
+
+		// Default handling for enum values
+		return processDefaultEnumFields(enumConstant);
+	}
+
+	/**
+	 * Get the value with @JsonValue annotation
+	 * <p>
 	 * This method retrieves the value of an enum based on its fields or methods. It
 	 * supports loading the enum class via reflection and determines the enum value based
 	 * on the presence of specific annotations such as {@code JsonValue}
@@ -377,9 +404,8 @@ public static Object getEnumValue(JavaClass javaClass, ProjectDocConfigBuilder b
 	 * @return Object The enum value, whose type depends on the specific enum definition
 	 * @throws RuntimeException If the enum constants do not exist
 	 */
-	public static Object getDefaultEnumValue(JavaClass javaClass, ProjectDocConfigBuilder builder,
+	private static Object getEnumValueWithJsonValue(JavaClass javaClass, ProjectDocConfigBuilder builder,
 			JavaField enumConstant) {
-		// Try getting value from method with JsonValue annotation
 		String methodName = findMethodWithJsonValue(javaClass);
 		if (Objects.nonNull(methodName)) {
 			Class<?> enumClass = loadEnumClass(javaClass, builder);
@@ -399,8 +425,7 @@ public static Object getDefaultEnumValue(JavaClass javaClass, ProjectDocConfigBu
 			return null;
 		}
 
-		// Default handling for enum values
-		return processDefaultEnumFields(enumConstant);
+		return null;
 	}
 
 	/**
@@ -1399,10 +1424,12 @@ public static List<AnnotationValue> getAnnotationValues(JavaAnnotation javaAnnot
 	 * @param javaClass The Java class object representing the enum.
 	 * @param builder The project documentation configuration builder, used to access
 	 * project-specific documentation settings.
+	 * @param jsonEnum Whether it is an enum in JSON
 	 * @return An EnumInfoAndValues object containing both the enum information and its
 	 * values.
 	 */
-	public static EnumInfoAndValues getEnumInfoAndValue(JavaClass javaClass, ProjectDocConfigBuilder builder) {
+	public static EnumInfoAndValues getEnumInfoAndValue(JavaClass javaClass, ProjectDocConfigBuilder builder,
+			boolean jsonEnum) {
 		// Step 1: Retrieve EnumInfo (general enum info like name, description, etc.)
 		EnumInfo enumInfo = getEnumInfo(javaClass, builder);
 
@@ -1411,7 +1438,7 @@ public static EnumInfoAndValues getEnumInfoAndValue(JavaClass javaClass, Project
 			return null;
 		}
 
-		return generateEnumInfoAndValues(enumInfo, builder);
+		return generateEnumInfoAndValues(enumInfo, javaClass, builder, jsonEnum);
 	}
 
 	/**
@@ -1451,7 +1478,7 @@ private static List<Item> getEnumItemList(JavaClass enumClass, ApiDataDictionary
 			String enumComment = cons.getComment();
 			item.setName(name);
 			item.setValue(name);
-			item.setType("string");
+			item.setType(ParamTypeConstants.PARAM_TYPE_ENUM);
 			item.setDescription(enumComment);
 
 			Object defaultEnumValue = getDefaultEnumValue(enumClass, builder, cons);
@@ -1473,26 +1500,41 @@ private static List<Item> getEnumItemList(JavaClass enumClass, ApiDataDictionary
 	 * Generate EnumInfoAndValues, and determine the enumNameExample configuration in
 	 * apiConfig
 	 * @param enumInfo the enum info
+	 * @param javaClass The Java class object representing the enum.
 	 * @param builder builder
+	 * @param jsonEnum Whether it is an enum in JSON
 	 * @return List<Item>
 	 * @author JasonKung22
 	 */
-	private static EnumInfoAndValues generateEnumInfoAndValues(EnumInfo enumInfo, ProjectDocConfigBuilder builder) {
+	private static EnumInfoAndValues generateEnumInfoAndValues(EnumInfo enumInfo, JavaClass javaClass,
+			ProjectDocConfigBuilder builder, boolean jsonEnum) {
 		ApiConfig apiConfig = builder.getApiConfig();
 		List<Item> items = enumInfo.getItems();
-		String enumValue;
-		List<String> enumValues;
-		String type;
-		if (apiConfig.isEnumNameExample()) {
-			enumValues = items.stream().map(Item::getName).collect(Collectors.toList());
-			enumValue = enumValues.get(0);
-			type = "string";
+		String enumValue = null;
+		List<String> enumValues = null;
+		String type = null;
+
+		if (jsonEnum || apiConfig.isEnumConvertor()) {
+			List<JavaField> enumConstants = javaClass.getEnumConstants();
+			List<Object> enumValueList = enumConstants.stream()
+				.map(cons -> getEnumValueWithJsonValue(javaClass, builder, cons))
+				.filter(Objects::nonNull)
+				.collect(Collectors.toList());
+
+			if (CollectionUtil.isNotEmpty(enumValueList)) {
+				Object enumValueWithJsonValue = enumValueList.get(0);
+				type = DocClassUtil.processTypeNameForParams(enumValueWithJsonValue.getClass().getCanonicalName());
+				enumValue = String.valueOf(enumValueWithJsonValue);
+				enumValues = enumValueList.stream().map(String::valueOf).collect(Collectors.toList());
+			}
 		}
-		else {
-			enumValues = items.stream().map(Item::getValue).collect(Collectors.toList());
+
+		if (enumValue == null) {
+			enumValues = items.stream().map(Item::getName).collect(Collectors.toList());
 			enumValue = enumValues.get(0);
-			type = items.get(0).getType();
+			type = ParamTypeConstants.PARAM_TYPE_ENUM;
 		}
+
 		return EnumInfoAndValues.builder()
 			.setEnumInfo(enumInfo)
 			.setEnumValues(enumValues)

src/main/java/com/ly/doc/utils/ParamUtil.java

@@ -91,7 +91,7 @@ public static JavaClass handleSeeEnum(ApiParam param, JavaField javaField, Proje
 				javaField.getType().getGenericFullyQualifiedName())) {
 			param.setType(ParamTypeConstants.PARAM_TYPE_ENUM);
 		}
-		EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(seeEnum, builder);
+		EnumInfoAndValues enumInfoAndValue = JavaClassUtil.getEnumInfoAndValue(seeEnum, builder, jsonRequest);
 		if (Objects.nonNull(enumInfoAndValue)) {
 			param.setValue(StringUtil.removeDoubleQuotes(String.valueOf(enumInfoAndValue.getValue())))
 				.setEnumInfoAndValues(enumInfoAndValue)

src/main/resources/default.json

@@ -11,7 +11,7 @@
   "skipTransientField": true,
   "requestExample": true,
   "responseExample": true,
-  "enumNameExample": false,
+  "enumConvertor": false,
   "revisionLogs": [
     {
       "version": "1.0",