feat: Add allowSelfReference configuration to control self-reference recursion in API documentation

Author: CaroLe-prw

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

@@ -527,7 +527,19 @@ else if (gName.length() == 1) {
 							}
 						}
 						else {
-							param.setSelfReferenceLoop(true);
+							// Check configuration for self-reference in collections
+							if (projectBuilder.getApiConfig().isAllowSelfReference()) {
+								// Allow limited recursion when enabled
+								if (level < 2) {
+									paramList.addAll(buildParams(gName, preBuilder.toString(), nextLevel, isRequired,
+											isResp, registryClasses, projectBuilder, groupClasses,
+											methodJsonViewClasses, fieldPid, jsonRequest, atomicInteger));
+								}
+							}
+							else {
+								// Original behavior: set self reference loop
+								param.setSelfReferenceLoop(true);
+							}
 						}
 					}
 
@@ -624,18 +636,32 @@ else if (gicName.contains("<")) {
 					}
 				}
 				else if (simpleName.equals(subTypeName)) {
-					// reference self
-					ApiParam param1 = ApiParam.of()
-						.setField(pre + fieldName)
-						.setPid(pid)
-						.setId(atomicOrDefault(atomicInteger, paramList.size() + pid + 1))
-						.setClassName(subTypeName)
-						.setMaxLength(maxLength)
-						.setType(ParamTypeConstants.PARAM_TYPE_OBJECT)
-						.setDesc(comment.append(" $ref... self").toString())
-						.setVersion(DocGlobalConstants.DEFAULT_VERSION)
-						.setExtensions(extensionParams);
-					paramList.add(param1);
+					// reference self - check configuration
+					if (projectBuilder.getApiConfig().isAllowSelfReference()) {
+						// Allow limited recursion when enabled
+						processApiParam(paramList, param, isRequired, comment + appendComment, since, strRequired);
+						fieldPid = Optional.ofNullable(atomicInteger).isPresent() ? param.getId()
+								: paramList.size() + pid;
+						if (level < 2) {
+							paramList.addAll(buildParams(fieldGicName, preBuilder.toString(), nextLevel, isRequired,
+									isResp, registryClasses, projectBuilder, groupClasses, methodJsonViewClasses,
+									fieldPid, jsonRequest, atomicInteger));
+						}
+					}
+					else {
+						// Original behavior: create reference parameter
+						ApiParam param1 = ApiParam.of()
+							.setField(pre + fieldName)
+							.setPid(pid)
+							.setId(atomicOrDefault(atomicInteger, paramList.size() + pid + 1))
+							.setClassName(subTypeName)
+							.setMaxLength(maxLength)
+							.setType(ParamTypeConstants.PARAM_TYPE_OBJECT)
+							.setDesc(comment.append(" $ref... self").toString())
+							.setVersion(DocGlobalConstants.DEFAULT_VERSION)
+							.setExtensions(extensionParams);
+						paramList.add(param1);
+					}
 				}
 				else {
 					processApiParam(paramList, param, isRequired, comment + appendComment, since, strRequired);

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

@@ -496,6 +496,13 @@ public class ApiConfig {
 	 */
 	private boolean enumConvertor = Boolean.FALSE;
 
+	/**
+	 * allow self reference recursion
+	 *
+	 * @since 3.1.0
+	 */
+	private boolean allowSelfReference = Boolean.FALSE;
+
 	public static ApiConfig getInstance() {
 		return instance;
 	}
@@ -1185,6 +1192,14 @@ public void setEnumConvertor(boolean enumConvertor) {
 		this.enumConvertor = enumConvertor;
 	}
 
+	public boolean isAllowSelfReference() {
+		return allowSelfReference;
+	}
+
+	public void setAllowSelfReference(boolean allowSelfReference) {
+		this.allowSelfReference = allowSelfReference;
+	}
+
 	public OpenApiTagNameTypeEnum getOpenApiTagNameType() {
 		return openApiTagNameType;
 	}