springdoc-openapi-javadoc doesn't work with @ParameterObject. Fixes #1324.

Author: bnasslahsen

springdoc-openapi-common/src/main/java/org/springdoc/api/AbstractOpenApiResource.java

@@ -106,6 +106,7 @@
 import org.springframework.web.method.HandlerMethod;
 
 import static org.springdoc.core.Constants.ACTUATOR_DEFAULT_GROUP;
+import static org.springdoc.core.Constants.DOT;
 import static org.springdoc.core.Constants.LINKS_SCHEMA_CUSTOMISER;
 import static org.springdoc.core.Constants.OPERATION_ATTRIBUTE;
 import static org.springdoc.core.Constants.SPRING_MVC_SERVLET_PATH;
@@ -667,10 +668,10 @@ protected boolean isPackageToScan(Package aPackage) {
 		}
 		boolean include = CollectionUtils.isEmpty(packagesToScan)
 				|| packagesToScan.stream().anyMatch(pack -> packageName.equals(pack)
-				|| packageName.startsWith(pack + "."));
+				|| packageName.startsWith(pack + DOT));
 		boolean exclude = !CollectionUtils.isEmpty(packagesToExclude)
 				&& (packagesToExclude.stream().anyMatch(pack -> packageName.equals(pack)
-				|| packageName.startsWith(pack + ".")));
+				|| packageName.startsWith(pack + DOT)));
 
 		return include && !exclude;
 	}

springdoc-openapi-common/src/main/java/org/springdoc/core/AbstractRequestService.java

@@ -21,6 +21,7 @@
 package org.springdoc.core;
 
 import java.lang.annotation.Annotation;
+import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 import java.math.BigDecimal;
 import java.util.ArrayList;
@@ -58,6 +59,7 @@
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.ClassUtils;
 import org.apache.commons.lang3.StringUtils;
+import org.apache.commons.lang3.reflect.FieldUtils;
 import org.springdoc.core.customizers.ParameterCustomizer;
 
 import org.springframework.core.LocalVariableTableParameterNameDiscoverer;
@@ -78,6 +80,7 @@
 import org.springframework.web.method.HandlerMethod;
 import org.springframework.web.util.UriComponentsBuilder;
 
+import static org.springdoc.core.Constants.DOT;
 import static org.springdoc.core.Constants.OPENAPI_ARRAY_TYPE;
 import static org.springdoc.core.Constants.OPENAPI_STRING_TYPE;
 import static org.springdoc.core.Constants.QUERY_PARAM;
@@ -267,7 +270,7 @@ public Operation build(HandlerMethod handlerMethod, RequestMethod requestMethod,
 				if (isValidParameter(parameter)) {
 					// Add param javadoc
 					if (StringUtils.isBlank(parameter.getDescription()) && javadocProvider != null) {
-						String paramJavadocDescription = javadocProvider.getParamJavadoc(handlerMethod.getMethod(), pName);
+						String paramJavadocDescription = getParamJavadoc(javadocProvider, methodParameter, pName);
 						if (!StringUtils.isBlank(paramJavadocDescription)) {
 							parameter.setDescription(paramJavadocDescription);
 						}
@@ -281,7 +284,7 @@ else if (!RequestMethod.GET.equals(requestMethod)) {
 							parameterInfo, requestBodyInfo);
 					// Add requestBody javadoc
 					if (StringUtils.isBlank(requestBodyInfo.getRequestBody().getDescription()) && javadocProvider != null) {
-						String paramJavadocDescription = javadocProvider.getParamJavadoc(handlerMethod.getMethod(), pName);
+						String paramJavadocDescription = getParamJavadoc(javadocProvider, methodParameter, pName);
 						if (!StringUtils.isBlank(paramJavadocDescription)) {
 							requestBodyInfo.getRequestBody().setDescription(paramJavadocDescription);
 						}
@@ -671,4 +674,29 @@ private boolean isRequestBodyParam(RequestMethod requestMethod, ParameterInfo pa
 						|| (!ClassUtils.isPrimitiveOrWrapper(methodParameter.getParameter().getType()) && (!ArrayUtils.isEmpty(methodParameter.getParameterAnnotations()) || length == 1)));
 	}
 
+	/**
+	 * Gets param javadoc.
+	 *
+	 * @param javadocProvider the javadoc provider
+	 * @param methodParameter the method parameter
+	 * @param pName the p name
+	 * @return the param javadoc
+	 */
+	private String getParamJavadoc(JavadocProvider javadocProvider, MethodParameter methodParameter, String pName) {
+		DelegatingMethodParameter delegatingMethodParameter = (DelegatingMethodParameter) methodParameter;
+		final String paramJavadocDescription;
+		if (delegatingMethodParameter.isParameterObject()) {
+			String fieldName;
+			if (pName.contains(DOT))
+				fieldName = StringUtils.substringAfter(pName, DOT);
+			else
+				fieldName = pName;
+			Field field = FieldUtils.getDeclaredField(((DelegatingMethodParameter) methodParameter).getExecutable().getDeclaringClass(), fieldName, true);
+			paramJavadocDescription = javadocProvider.getFieldJavadoc(field);
+		}
+		else
+			paramJavadocDescription = javadocProvider.getParamJavadoc(methodParameter.getMethod(), pName);
+		return paramJavadocDescription;
+	}
+
 }

springdoc-openapi-common/src/main/java/org/springdoc/core/Constants.java

@@ -65,10 +65,15 @@ public final class Constants {
 	 */
 	public static final String YAML = "yaml";
 
+	/**
+	 * The constant DOT.
+	 */
+	public static final String DOT = ".";
+
 	/**
 	 * The constant DEFAULT_API_DOCS_URL_YAML.
 	 */
-	public static final String DEFAULT_API_DOCS_URL_YAML = API_DOCS_URL + "." + YAML;
+	public static final String DEFAULT_API_DOCS_URL_YAML = API_DOCS_URL + DOT + YAML;
 
 	/**
 	 * The constant SPRINGDOC_ENABLED.

springdoc-openapi-common/src/main/java/org/springdoc/core/MethodParameterPojoExtractor.java

@@ -49,6 +49,8 @@
 
 import org.springframework.core.MethodParameter;
 
+import static org.springdoc.core.Constants.DOT;
+
 /**
  * The type Method parameter pojo extractor.
  * @author bnasslahsen
@@ -129,7 +131,7 @@ private static Stream<MethodParameter> fromGetterOfField(Class<?> paramClass, Fi
 		else if (field.getGenericType() instanceof TypeVariable<?>)
 			return extractTypeParameter(paramClass, (TypeVariable<?>) field.getGenericType(), field, fieldNamePrefix);
 		else
-			return extractFrom(field.getType(), fieldNamePrefix + field.getName() + ".");
+			return extractFrom(field.getType(), fieldNamePrefix + field.getName() + DOT);
 	}
 
 	/**

springdoc-openapi-javadoc/src/test/java/test/org/springdoc/api/app121/InheritedRequestParams.java

@@ -2,17 +2,14 @@
 
 import javax.validation.constraints.NotBlank;
 
-import io.swagger.v3.oas.annotations.Parameter;
-
 /**
  * The type Inherited request params.
  */
 public class InheritedRequestParams extends RequestParams {
 
 	/**
-	 * The Child param.
+	 * parameter from child of RequestParams
 	 */
-	@Parameter(description = "parameter from child of RequestParams")
 	@NotBlank
 	private String childParam;
 

springdoc-openapi-javadoc/src/test/resources/results/app102.json

@@ -49,6 +49,7 @@
           {
             "name": "stringParam1",
             "in": "query",
+            "description": "The String param 1.",
             "required": false,
             "deprecated": true,
             "schema": {
@@ -77,6 +78,7 @@
           {
             "name": "intParam2",
             "in": "query",
+            "description": "The Int param 2.",
             "required": false,
             "schema": {
               "type": "string"
@@ -85,6 +87,7 @@
           {
             "name": "intParam3",
             "in": "query",
+            "description": "The Int param 3.",
             "required": false,
             "schema": {
               "type": "string"
@@ -93,6 +96,7 @@
           {
             "name": "nested.param1",
             "in": "query",
+            "description": "The Param 1.",
             "required": false,
             "schema": {
               "type": "string"
@@ -101,6 +105,7 @@
           {
             "name": "nested.param2",
             "in": "query",
+            "description": "The Param 2.",
             "required": false,
             "schema": {
               "type": "integer"
@@ -109,6 +114,7 @@
           {
             "name": "nestedList",
             "in": "query",
+            "description": "The Nested list.",
             "required": false,
             "schema": {
               "type": "array",

springdoc-openapi-javadoc/src/test/resources/results/app121.json

@@ -49,6 +49,7 @@
           {
             "name": "stringParam1",
             "in": "query",
+            "description": "The String param 1.",
             "required": false,
             "deprecated": true,
             "schema": {
@@ -77,6 +78,7 @@
           {
             "name": "intParam2",
             "in": "query",
+            "description": "The Int param 2.",
             "required": false,
             "schema": {
               "type": "string"
@@ -85,6 +87,7 @@
           {
             "name": "intParam3",
             "in": "query",
+            "description": "The Int param 3.",
             "required": false,
             "schema": {
               "type": "string"
@@ -93,6 +96,7 @@
           {
             "name": "nested.param1",
             "in": "query",
+            "description": "The Param 1.",
             "required": false,
             "schema": {
               "type": "string"
@@ -101,6 +105,7 @@
           {
             "name": "nested.param2",
             "in": "query",
+            "description": "The Param 2.",
             "required": false,
             "schema": {
               "type": "integer"
@@ -109,6 +114,7 @@
           {
             "name": "nestedList",
             "in": "query",
+            "description": "The Nested list.",
             "required": false,
             "schema": {
               "type": "array",
@@ -192,7 +198,7 @@
           },
           "childParam": {
             "type": "string",
-            "description": "The Child param."
+            "description": "parameter from child of RequestParams"
           }
         }
       }

springdoc-openapi-javadoc/src/test/resources/results/app155.json

@@ -22,6 +22,7 @@
           {
             "name": "primitiveConcreteField",
             "in": "query",
+            "description": "The Primitive concrete field.",
             "required": false,
             "schema": {
               "type": "integer",
@@ -31,6 +32,7 @@
           {
             "name": "primitiveBaseField",
             "in": "query",
+            "description": "The Primitive base field.",
             "required": false,
             "schema": {
               "type": "integer",
@@ -40,6 +42,7 @@
           {
             "name": "genericField",
             "in": "query",
+            "description": "The Generic field.",
             "required": false,
             "schema": {
               "type": "string",
@@ -75,6 +78,7 @@
           {
             "name": "primitiveConcreteField",
             "in": "query",
+            "description": "The Primitive concrete field.",
             "required": false,
             "schema": {
               "type": "integer",
@@ -84,6 +88,7 @@
           {
             "name": "primitiveBaseField",
             "in": "query",
+            "description": "The Primitive base field.",
             "required": false,
             "schema": {
               "type": "integer",
@@ -93,6 +98,7 @@
           {
             "name": "genericField",
             "in": "query",
+            "description": "The Generic field.",
             "required": false,
             "schema": {
               "type": "integer",

springdoc-openapi-javadoc/target/apidocs/allclasses-frame.html

@@ -0,0 +1,22 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!-- NewPage -->
+<html lang="fr">
+<head>
+<!-- Generated by javadoc (1.8.0_275) on Tue Oct 19 12:24:25 CEST 2021 -->
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>All Classes (springdoc-openapi-javadoc 1.5.12-SNAPSHOT API)</title>
+<meta name="date" content="2021-10-19">
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
+<script type="text/javascript" src="script.js"></script>
+</head>
+<body>
+<h1 class="bar">All&nbsp;Classes</h1>
+<div class="indexContainer">
+<ul>
+<li><a href="org/springdoc/openapi/javadoc/JavadocPropertyCustomizer.html" title="class in org.springdoc.openapi.javadoc" target="classFrame">JavadocPropertyCustomizer</a></li>
+<li><a href="org/springdoc/openapi/javadoc/SpringDocJavadocConfiguration.html" title="class in org.springdoc.openapi.javadoc" target="classFrame">SpringDocJavadocConfiguration</a></li>
+<li><a href="org/springdoc/openapi/javadoc/SpringDocJavadocProvider.html" title="class in org.springdoc.openapi.javadoc" target="classFrame">SpringDocJavadocProvider</a></li>
+</ul>
+</div>
+</body>
+</html>

springdoc-openapi-javadoc/target/apidocs/allclasses-noframe.html

@@ -0,0 +1,22 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!-- NewPage -->
+<html lang="fr">
+<head>
+<!-- Generated by javadoc (1.8.0_275) on Tue Oct 19 12:24:25 CEST 2021 -->
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>All Classes (springdoc-openapi-javadoc 1.5.12-SNAPSHOT API)</title>
+<meta name="date" content="2021-10-19">
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
+<script type="text/javascript" src="script.js"></script>
+</head>
+<body>
+<h1 class="bar">All&nbsp;Classes</h1>
+<div class="indexContainer">
+<ul>
+<li><a href="org/springdoc/openapi/javadoc/JavadocPropertyCustomizer.html" title="class in org.springdoc.openapi.javadoc">JavadocPropertyCustomizer</a></li>
+<li><a href="org/springdoc/openapi/javadoc/SpringDocJavadocConfiguration.html" title="class in org.springdoc.openapi.javadoc">SpringDocJavadocConfiguration</a></li>
+<li><a href="org/springdoc/openapi/javadoc/SpringDocJavadocProvider.html" title="class in org.springdoc.openapi.javadoc">SpringDocJavadocProvider</a></li>
+</ul>
+</div>
+</body>
+</html>