refactor: ♻️ optimize custom field logic and update related models

.github/workflows/build-and-run-example-project.yml

@@ -31,15 +31,15 @@ jobs:
       - name: Update Version in pom.xml
         run: mvn versions:set -DnewVersion="${{ env.smart-doc-version }}" -DgenerateBackupPoms=false
 
-      - name: Build and Install Plugin
+      - name: Build and Install
         run: |
-          mvn install 2>&1 | tee logs/build.log
+          mvn install -DskipTests=true 2>&1 | tee logs/build.log
           if grep -E "\[ERROR\]" logs/build.log; then
             cat logs/build.log
             exit 1
           fi
 
-      - name: Upload Plugin Artifact
+      - name: Upload Artifact
         id: upload-artifact
         uses: actions/upload-artifact@v4
         with:

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2018-2024 smart-doc
+ * Copyright (C) 2018-2025 smart-doc
  *
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -227,15 +227,18 @@ else if (CollectionUtil.isEmpty(groupClasses)) {
 	 * Get the custom field information for a given field.
 	 * @param projectBuilder the project builder
 	 * @param docField the doc of java field
-	 * @param customResponseField the custom response field
-	 * @param customRequestField the custom request field
 	 * @param isResp the response flag for the parameter
 	 * @param simpleName the simple name of the field
+	 * @param fieldName the name of the field
 	 * @return the custom field information {@link CustomFieldInfo}
-	 *
 	 */
 	protected static CustomFieldInfo getCustomFieldInfo(ProjectDocConfigBuilder projectBuilder, DocJavaField docField,
-			CustomField customResponseField, CustomField customRequestField, boolean isResp, String simpleName) {
+			boolean isResp, String simpleName, String fieldName) {
+		CustomField.Key key = CustomField.Key.create(docField.getDeclaringClassName(), fieldName);
+
+		CustomField customResponseField = CustomField.nameEquals(key, projectBuilder.getCustomRespFieldMap());
+		CustomField customRequestField = CustomField.nameEquals(key, projectBuilder.getCustomReqFieldMap());
+
 		CustomFieldInfo customFieldInfo = new CustomFieldInfo();
 
 		// ignore custom field, if true return quickly
@@ -244,6 +247,8 @@ protected static CustomFieldInfo getCustomFieldInfo(ProjectDocConfigBuilder proj
 			return customFieldInfo;
 		}
 
+		customFieldInfo.setCustomResponseField(customResponseField).setCustomRequestField(customRequestField);
+
 		// cover response value
 		if (Objects.nonNull(customResponseField) && isResp && Objects.nonNull(customResponseField.getValue())
 				&& JavaClassUtil.isTargetChildClass(simpleName, customResponseField.getOwnerClassName())) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2018-2024 smart-doc
+ * Copyright (C) 2018-2025 smart-doc
  *
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -24,12 +24,33 @@
 import com.ly.doc.constants.DocGlobalConstants;
 import com.ly.doc.constants.DocTags;
 import com.ly.doc.constants.JavaTypeConstants;
-import com.ly.doc.model.*;
-import com.ly.doc.utils.*;
+import com.ly.doc.model.ApiReturn;
+import com.ly.doc.model.CustomField;
+import com.ly.doc.model.CustomFieldInfo;
+import com.ly.doc.model.DocJavaField;
+import com.ly.doc.model.DocJavaMethod;
+import com.ly.doc.model.FieldJsonAnnotationInfo;
+import com.ly.doc.utils.DocClassUtil;
+import com.ly.doc.utils.DocUtil;
+import com.ly.doc.utils.JavaClassUtil;
+import com.ly.doc.utils.JavaClassValidateUtil;
+import com.ly.doc.utils.JavaFieldUtil;
+import com.ly.doc.utils.JsonUtil;
 import com.power.common.util.StringUtil;
-import com.thoughtworks.qdox.model.*;
-
-import java.util.*;
+import com.thoughtworks.qdox.model.DocletTag;
+import com.thoughtworks.qdox.model.JavaAnnotation;
+import com.thoughtworks.qdox.model.JavaClass;
+import com.thoughtworks.qdox.model.JavaField;
+import com.thoughtworks.qdox.model.JavaMethod;
+import com.thoughtworks.qdox.model.JavaType;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
 
 import static com.ly.doc.constants.DocTags.IGNORE_RESPONSE_BODY_ADVICE;
 
@@ -276,8 +297,6 @@ else if (JavaClassValidateUtil.isReactor(typeName)) {
 				if (Boolean.TRUE.equals(annotationInfo.getIgnore())) {
 					continue;
 				}
-				// the param type from @JsonFormat
-				String fieldJsonFormatType = annotationInfo.getFieldJsonFormatType();
 				// the param value from @JsonFormat
 				String fieldJsonFormatValue = annotationInfo.getFieldJsonFormatValue();
 				// has Annotation @JsonSerialize And using ToStringSerializer
@@ -288,12 +307,9 @@ else if (JavaClassValidateUtil.isReactor(typeName)) {
 
 				String typeSimpleName = docField.getTypeSimpleName();
 				String fieldGicName = docField.getTypeGenericCanonicalName();
-				CustomField.Key key = CustomField.Key.create(docField.getDeclaringClassName(), fieldName);
 
-				CustomField customResponseField = CustomField.nameEquals(key, projectBuilder.getCustomRespFieldMap());
-				CustomField customRequestField = CustomField.nameEquals(key, projectBuilder.getCustomReqFieldMap());
-				CustomFieldInfo customFieldInfo = getCustomFieldInfo(projectBuilder, docField, customResponseField,
-						customRequestField, isResp, typeSimpleName);
+				CustomFieldInfo customFieldInfo = getCustomFieldInfo(projectBuilder, docField, isResp, typeSimpleName,
+						fieldName);
 				// ignore custom field
 				if (Boolean.TRUE.equals(customFieldInfo.getIgnore())) {
 					continue;
@@ -322,6 +338,9 @@ else if (JavaClassValidateUtil.isReactor(typeName)) {
 									: valueByTypeAndFieldName;
 						}
 					}
+
+					CustomField customResponseField = customFieldInfo.getCustomResponseField();
+					CustomField customRequestField = customFieldInfo.getCustomRequestField();
 					if (Objects.nonNull(customRequestField) && !isResp
 							&& typeName.equals(customRequestField.getOwnerClassName())) {
 						JavaFieldUtil.buildCustomField(result, typeSimpleName, customRequestField);

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

@@ -1,7 +1,7 @@
 /*
  * smart-doc https://github.com/smart-doc-group/smart-doc
  *
- * Copyright (C) 2018-2024 smart-doc
+ * Copyright (C) 2018-2025 smart-doc
  *
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -32,7 +32,6 @@
 import com.ly.doc.model.ApiConfig;
 import com.ly.doc.model.ApiDataDictionary;
 import com.ly.doc.model.ApiParam;
-import com.ly.doc.model.CustomField;
 import com.ly.doc.model.CustomFieldInfo;
 import com.ly.doc.model.DocJavaField;
 import com.ly.doc.model.FieldJsonAnnotationInfo;
@@ -271,13 +270,9 @@ private static List<ApiParam> processFields(String className, String pre, int le
 			}
 
 			boolean strRequired = false;
-			CustomField.Key key = CustomField.Key.create(docField.getDeclaringClassName(), fieldName);
 
-			CustomField customResponseField = CustomField.nameEquals(key, projectBuilder.getCustomRespFieldMap());
-			CustomField customRequestField = CustomField.nameEquals(key, projectBuilder.getCustomReqFieldMap());
-
-			CustomFieldInfo customFieldInfo = getCustomFieldInfo(projectBuilder, docField, customResponseField,
-					customRequestField, isResp, simpleName);
+			CustomFieldInfo customFieldInfo = getCustomFieldInfo(projectBuilder, docField, isResp, typeSimpleName,
+					fieldName);
 			// ignore custom field
 			if (Boolean.TRUE.equals(customFieldInfo.getIgnore())) {
 				continue;

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

@@ -1,3 +1,25 @@
+/*
+ * smart-doc https://github.com/smart-doc-group/smart-doc
+ *
+ * Copyright (C) 2018-2025 smart-doc
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
 package com.ly.doc.model;
 
 import java.io.Serializable;
@@ -15,6 +37,16 @@ public class CustomFieldInfo implements Serializable {
 	 */
 	private static final long serialVersionUID = -7310122325722122250L;
 
+	/**
+	 * custom response field
+	 */
+	private CustomField customResponseField;
+
+	/**
+	 * custom request field
+	 */
+	private CustomField customRequestField;
+
 	/**
 	 * ignore
 	 */
@@ -40,6 +72,24 @@ public class CustomFieldInfo implements Serializable {
 	 */
 	private String comment;
 
+	public CustomField getCustomResponseField() {
+		return customResponseField;
+	}
+
+	public CustomFieldInfo setCustomResponseField(CustomField customResponseField) {
+		this.customResponseField = customResponseField;
+		return this;
+	}
+
+	public CustomField getCustomRequestField() {
+		return customRequestField;
+	}
+
+	public CustomFieldInfo setCustomRequestField(CustomField customRequestField) {
+		this.customRequestField = customRequestField;
+		return this;
+	}
+
 	public Boolean getIgnore() {
 		return ignore;
 	}