Improve javadoc support.

Author: bnasslahsen

springdoc-openapi-javadoc/src/main/java/org/springdoc/openapi/javadoc/SpringDocJavadocProvider.java

@@ -22,8 +22,11 @@
 
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
+import java.util.ArrayList;
 import java.util.List;
+import java.util.stream.Collectors;
 
+import com.github.therapi.runtimejavadoc.ClassJavadoc;
 import com.github.therapi.runtimejavadoc.CommentFormatter;
 import com.github.therapi.runtimejavadoc.FieldJavadoc;
 import com.github.therapi.runtimejavadoc.MethodJavadoc;
@@ -50,7 +53,7 @@ public class SpringDocJavadocProvider implements JavadocProvider {
 	 */
 	@Override
 	public String getMethodJavadocDescription(Method method) {
-		MethodJavadoc methodJavadoc = RuntimeJavadoc.getJavadoc(method);
+		MethodJavadoc methodJavadoc = findMethodJavadoc(method);
 		return formatter.format(methodJavadoc.getComment());
 	}
 
@@ -62,7 +65,7 @@ public String getMethodJavadocDescription(Method method) {
 	 */
 	@Override
 	public String getMethodJavadocReturn(Method method) {
-		MethodJavadoc methodJavadoc = RuntimeJavadoc.getJavadoc(method);
+		MethodJavadoc methodJavadoc = findMethodJavadoc(method);
 		return formatter.format(methodJavadoc.getReturns());
 	}
 
@@ -75,7 +78,7 @@ public String getMethodJavadocReturn(Method method) {
 	 */
 	@Override
 	public String getParamJavadoc(Method method, String name) {
-		MethodJavadoc methodJavadoc = RuntimeJavadoc.getJavadoc(method);
+		MethodJavadoc methodJavadoc = findMethodJavadoc(method);
 		List<ParamJavadoc> paramsDoc = methodJavadoc.getParams();
 		return paramsDoc.stream().filter(paramJavadoc1 -> name.equals(paramJavadoc1.getName())).findAny()
 				.map(paramJavadoc1 -> formatter.format(paramJavadoc1.getComment())).orElse(null);
@@ -93,4 +96,61 @@ public String getFieldJavadoc(Field field) {
 		return formatter.format(fieldJavadoc.getComment());
 	}
 
+	/**
+	 * Find method javadoc method javadoc.
+	 *
+	 * @param method the method
+	 * @return the method javadoc
+	 */
+	private MethodJavadoc findMethodJavadoc(Method method) {
+		ClassJavadoc classJavadoc = RuntimeJavadoc.getJavadoc(method.getDeclaringClass());
+		List<MethodJavadoc> methodDocs = classJavadoc.getMethods();
+		// filter by method name
+		List<MethodJavadoc> methodDocByMethodName = methodDocs.stream().filter(methodJavadoc -> methodJavadoc.getName().equals(method.getName())).collect(Collectors.toList());
+		if (methodDocByMethodName.size() == 1)
+			return methodDocByMethodName.get(0);
+		// filter by parameters
+		if (methodDocByMethodName.size() > 1) {
+			List<MethodJavadoc> methodDocByParamType = methodDocByMethodName.stream().filter(methodJavadoc -> paramsMatch(method.getParameterTypes(), methodJavadoc.getParamTypes())).collect(Collectors.toList());
+			if (methodDocByParamType.size() == 1)
+				return methodDocByParamType.get(0);
+		}
+		return MethodJavadoc.createEmpty(method);
+	}
+
+	/**
+	 * Params match boolean.
+	 *
+	 * @param paramTypesClass the param types class
+	 * @param paramTypes the param types
+	 * @return the boolean
+	 */
+	private boolean paramsMatch(Class<?>[] paramTypesClass, List<String> paramTypes) {
+		List<String> paramTypesJavadoc = new ArrayList<>();
+		for (int i = 0; i < paramTypes.size(); i++) {
+			if (paramTypes.get(i).contains("::")) {
+				String[] paramTypeArray = paramTypes.get(i).split("::");
+				String paramType = paramTypeArray[paramTypeArray.length - 1].trim().replace(")", "");
+				paramTypesJavadoc.add(paramType);
+			}
+			else
+				paramTypesJavadoc.add(paramTypes.get(i));
+		}
+		return getCanonicalNames(paramTypesClass).equals(paramTypesJavadoc);
+	}
+
+	/**
+	 * Gets canonical names.
+	 *
+	 * @param paramTypes the param types
+	 * @return the canonical names
+	 */
+	private List<String> getCanonicalNames(Class<?>[] paramTypes) {
+		List<String> methodParamsTypes = new ArrayList<>();
+		for (Class<?> aClass : paramTypes) {
+			methodParamsTypes.add(aClass.getCanonicalName());
+		}
+		return methodParamsTypes;
+	}
+
 }

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

@@ -198,11 +198,13 @@
         "tags": [
           "items"
         ],
+        "description": "Show items list.",
         "operationId": "showItems",
         "parameters": [
           {
             "name": "cusID",
             "in": "query",
+            "description": "the customer id",
             "required": true,
             "schema": {
               "maxLength": 6,
@@ -213,6 +215,7 @@
           {
             "name": "toto",
             "in": "query",
+            "description": "the toto",
             "required": true,
             "schema": {
               "maximum": 6,
@@ -224,6 +227,7 @@
           {
             "name": "start",
             "in": "query",
+            "description": "the start date",
             "required": false,
             "schema": {
               "type": "string",
@@ -234,6 +238,7 @@
           {
             "name": "filterIds",
             "in": "query",
+            "description": "the filter ids",
             "required": false,
             "explode": false,
             "schema": {
@@ -256,7 +261,7 @@
             }
           },
           "200": {
-            "description": "OK",
+            "description": "the list",
             "content": {
               "application/json": {
                 "schema": {
@@ -274,8 +279,10 @@
         "tags": [
           "items"
         ],
+        "description": "Add item response entity.",
         "operationId": "addItem",
         "requestBody": {
+          "description": "the item dto",
           "content": {
             "application/json": {
               "schema": {
@@ -297,7 +304,7 @@
             }
           },
           "200": {
-            "description": "OK",
+            "description": "the response entity",
             "content": {
               "application/json": {
                 "schema": {

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

@@ -17,11 +17,13 @@
           "hello-ap1",
           "hello-ap2"
         ],
+        "description": "Gets all pets.",
         "operationId": "getAllPets",
         "parameters": [
           {
             "name": "toto",
             "in": "query",
+            "description": "the toto",
             "required": true,
             "schema": {
               "type": "string"
@@ -30,7 +32,7 @@
         ],
         "responses": {
           "200": {
-            "description": "OK",
+            "description": "the all pets",
             "content": {
               "application/xml": {
                 "schema": {