Merge pull request #967 from linwumingshi/fix/requestbody-queryparam-…

…docs

fix: 🐛 correct parameter documentation for `@RequestBody` and unannotated form parameters

src/main/java/com/ly/doc/constants/ApiParamEnum.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 2018-2024 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.constants;
+
+/**
+ * ParamEnum
+ *
+ * @author linwumingshi
+ * @since 3.0.10
+ */
+public enum ApiParamEnum {
+
+	/**
+	 * PathVariable，when param use `@PathVariable` annotation
+	 */
+	PATH,
+
+	/**
+	 * RequestParam
+	 */
+	QUERY,
+
+	/**
+	 * Body Param(from-data, x-www-form-urlencoded, raw(json))
+	 */
+	BODY,
+
+	;
+
+}

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

@@ -18,6 +18,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+
 package com.ly.doc.model;
 
 import com.ly.doc.constants.MediaType;
@@ -27,7 +28,13 @@
 import com.thoughtworks.qdox.model.JavaClass;
 
 import java.io.Serializable;
-import java.util.*;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
 
 /**
  * java api method info model.
@@ -340,6 +347,9 @@ public void setOrder(int order) {
 	}
 
 	public List<ApiParam> getRequestParams() {
+		if (Objects.isNull(this.requestParams)) {
+			return new ArrayList<>();
+		}
 		return requestParams;
 	}
 
@@ -412,6 +422,9 @@ public void setDeprecated(boolean deprecated) {
 	}
 
 	public List<ApiParam> getPathParams() {
+		if (Objects.isNull(this.pathParams)) {
+			return new ArrayList<>();
+		}
 		return pathParams;
 	}
 
@@ -420,6 +433,9 @@ public void setPathParams(List<ApiParam> pathParams) {
 	}
 
 	public List<ApiParam> getQueryParams() {
+		if (Objects.isNull(this.queryParams)) {
+			return new ArrayList<>();
+		}
 		return queryParams;
 	}
 

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

@@ -18,14 +18,20 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+
 package com.ly.doc.model;
 
+import java.io.Serializable;
 import java.util.List;
 
 /**
+ * Api request params
+ *
  * @author yu 2020/11/26.
  */
-public class ApiMethodReqParam {
+public class ApiMethodReqParam implements Serializable {
+
+	private static final long serialVersionUID = 1140834362473560188L;
 
 	/**
 	 * path params
@@ -38,7 +44,7 @@ public class ApiMethodReqParam {
 	private List<ApiParam> queryParams;
 
 	/**
-	 * http request params
+	 * http request params(body param)
 	 */
 	private List<ApiParam> requestParams;
 

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

@@ -18,22 +18,36 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+
 package com.ly.doc.model;
 
 import com.ly.doc.model.torna.EnumInfo;
 import com.ly.doc.model.torna.EnumInfoAndValues;
+import com.power.common.util.CollectionUtil;
 import org.apache.commons.lang3.StringUtils;
 
+import java.io.Serializable;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Stack;
+import java.util.function.Consumer;
+import java.util.stream.Stream;
 
 import static com.ly.doc.constants.DocGlobalConstants.PARAM_PREFIX;
 
 /**
+ * Api Parameter
+ *
  * @author yu 2019/9/27.
+ * @since 1.7.2
  */
-public class ApiParam {
+public class ApiParam implements Serializable {
+
+	/**
+	 * serialVersionUID
+	 */
+	private static final long serialVersionUID = -714676579813604423L;
 
 	/**
 	 * param class name
@@ -249,6 +263,11 @@ public ApiParam setQueryParam(boolean queryParam) {
 		return this;
 	}
 
+	public ApiParam setQueryParamTrue() {
+		this.queryParam = true;
+		return this;
+	}
+
 	public String getValue() {
 		return value;
 	}
@@ -351,6 +370,43 @@ public ApiParam setEnumInfoAndValues(EnumInfoAndValues enumInfoAndValues) {
 		return this;
 	}
 
+	/**
+	 * Returns a stream containing the current parameter and all its child parameters.
+	 * @return a stream of the current parameter and all its descendants
+	 */
+	public Stream<ApiParam> flattenStream() {
+		Stream<ApiParam> selfStream = Stream.of(this);
+		Stream<ApiParam> childrenStream = (this.children == null) ? Stream.empty()
+				: this.children.stream().flatMap(ApiParam::flattenStream);
+		return Stream.concat(selfStream, childrenStream);
+	}
+
+	/**
+	 * Traverses this {@link ApiParam} and all its child parameters using a stack-based
+	 * depth-first traversal, applying the given consumer to each parameter.
+	 * @param consumer the operation to be performed on each {@link ApiParam}
+	 */
+	public void traverseAndConsume(Consumer<ApiParam> consumer) {
+		// Initialize a stack with the current instance
+		Stack<ApiParam> stack = new Stack<>();
+		stack.push(this);
+
+		// Traverse the parameter tree
+		while (!stack.isEmpty()) {
+			// Pop the current parameter from the stack
+			ApiParam current = stack.pop();
+			// Apply the provided consumer to the current parameter
+			consumer.accept(current);
+
+			// If the current parameter has children, push them onto the stack
+			if (CollectionUtil.isNotEmpty(current.getChildren())) {
+				for (ApiParam child : current.getChildren()) {
+					stack.push(child);
+				}
+			}
+		}
+	}
+
 	@Override
 	public String toString() {
 		return "ApiParam{" + "className='" + className + '\'' + ", id=" + id + ", field='" + field + '\'' + ", type='"

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

@@ -18,17 +18,23 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package com.ly.doc.model;
 
-import java.util.List;
+package com.ly.doc.model;
 
 import com.thoughtworks.qdox.model.JavaAnnotation;
 import com.thoughtworks.qdox.model.JavaParameter;
 
+import java.io.Serializable;
+import java.util.List;
+import java.util.Objects;
+
 /**
+ * Doc Java Parameter
+ *
  * @author yu3.sun on 2022/10/15
+ * @since 2.6.0
  */
-public class DocJavaParameter {
+public class DocJavaParameter implements Serializable {
 
 	private JavaParameter javaParameter;
 
@@ -40,7 +46,7 @@ public class DocJavaParameter {
 
 	private String typeValue;
 
-	List<JavaAnnotation> annotations;
+	private List<JavaAnnotation> annotations;
 
 	public JavaParameter getJavaParameter() {
 		return javaParameter;
@@ -90,4 +96,39 @@ public void setAnnotations(List<JavaAnnotation> annotations) {
 		this.annotations = annotations;
 	}
 
+	@Override
+	public String toString() {
+		return "DocJavaParameter{" + "javaParameter=" + javaParameter + ", genericCanonicalName='"
+				+ genericCanonicalName + '\'' + ", genericFullyQualifiedName='" + genericFullyQualifiedName + '\''
+				+ ", fullyQualifiedName='" + fullyQualifiedName + '\'' + ", typeValue='" + typeValue + '\''
+				+ ", annotations=" + annotations + '}';
+	}
+
+	@Override
+	public int hashCode() {
+		int result = javaParameter != null ? javaParameter.hashCode() : 0;
+		result = 31 * result + (genericCanonicalName != null ? genericCanonicalName.hashCode() : 0);
+		result = 31 * result + (genericFullyQualifiedName != null ? genericFullyQualifiedName.hashCode() : 0);
+		result = 31 * result + (fullyQualifiedName != null ? fullyQualifiedName.hashCode() : 0);
+		result = 31 * result + (typeValue != null ? typeValue.hashCode() : 0);
+		result = 31 * result + (annotations != null ? annotations.hashCode() : 0);
+		return result;
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if (this == obj) {
+			return true;
+		}
+		if (obj == null || getClass() != obj.getClass()) {
+			return false;
+		}
+		DocJavaParameter that = (DocJavaParameter) obj;
+		return (Objects.equals(javaParameter, that.javaParameter))
+				&& (Objects.equals(genericCanonicalName, that.genericCanonicalName))
+				&& (Objects.equals(genericFullyQualifiedName, that.genericFullyQualifiedName))
+				&& (Objects.equals(fullyQualifiedName, that.fullyQualifiedName))
+				&& (Objects.equals(typeValue, that.typeValue)) && (Objects.equals(annotations, that.annotations));
+	}
+
 }