open-api: expand query doc from beans

- #3729

Author: jknack

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/AnnotationParser.java

@@ -306,12 +306,7 @@ public static List<OperationExt> parse(ParserContext ctx, String prefix, Type ty
                                       .findFirst()
                                       .map(ParameterExt.class::cast)
                                       .orElse(null);
-                              var paramDoc =
-                                  methodDoc.getParameterDoc(
-                                      parameterName,
-                                      Optional.ofNullable(paramExt)
-                                          .map(ParameterExt::getContainerType)
-                                          .orElse(null));
+                              var paramDoc = methodDoc.getParameterDoc(parameterName);
                               if (paramDoc != null) {
                                 if (paramExt == null) {
                                   operationExt.getRequestBody().setDescription(paramDoc);

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/ParameterExt.java

@@ -10,9 +10,6 @@
 import com.fasterxml.jackson.annotation.JsonIgnore;
 
 public class ParameterExt extends io.swagger.v3.oas.models.parameters.Parameter {
-  /* keep track of expanded query bean parameters. */
-  @JsonIgnore private String containerType;
-
   @JsonIgnore private String javaType;
 
   @JsonIgnore private Object defaultValue;
@@ -27,14 +24,6 @@ public String getJavaType() {
     return javaType;
   }
 
-  public void setContainerType(String containerType) {
-    this.containerType = containerType;
-  }
-
-  public String getContainerType() {
-    return containerType;
-  }
-
   public Object getDefaultValue() {
     if (defaultValue != null) {
       if (javaType.equals(boolean.class.getName())) {

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RouteParser.java

@@ -169,18 +169,25 @@ private List<Parameter> checkParameters(ParserContext ctx, List<Parameter> param
                 .isPresent();
         if (expand) {
           SchemaRef ref = ctx.schemaRef(javaType).get();
+          var doc = ctx.javadoc().parse(javaType).orElse(null);
           for (Object e : ref.schema.getProperties().entrySet()) {
             String name = (String) ((Map.Entry) e).getKey();
             Schema s = (Schema) ((Map.Entry) e).getValue();
             var schemaMap = Json.mapper().convertValue(s, Map.class);
             schemaMap.remove("description");
             var schemaNoDesc = Json.mapper().convertValue(schemaMap, Schema.class);
             ParameterExt p = new ParameterExt();
-            p.setContainerType(javaType);
             p.setName(name);
             p.setIn(parameter.getIn());
             p.setSchema(schemaNoDesc);
+            // default doc
             p.setDescription(parameter.getDescription());
+            if (doc != null) {
+              var propertyDoc = doc.getPropertyDoc(name);
+              if (propertyDoc != null) {
+                p.setDescription(propertyDoc);
+              }
+            }
 
             params.add(p);
           }

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/MethodDoc.java

@@ -50,13 +50,6 @@ public List<String> getParameterNames() {
   }
 
   public String getParameterDoc(String name) {
-    return getParameterDoc(name, null);
-  }
-
-  public String getParameterDoc(String name, String in) {
-    if (in != null) {
-      return context.parse(in).map(bean -> bean.getPropertyDoc(name)).orElse(null);
-    }
     return tree(javadoc)
         // must be a tag
         .filter(javadocToken(JavadocTokenTypes.JAVADOC_TAG))

modules/jooby-openapi/src/test/java/issues/i3729/api/ApiDocTest.java

@@ -96,17 +96,17 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "      parameters:\n"
             + "      - name: title\n"
             + "        in: query\n"
-            + "        description: Book's param query.\n"
+            + "        description: Book's title.\n"
             + "        schema:\n"
             + "          type: string\n"
             + "      - name: author\n"
             + "        in: query\n"
-            + "        description: Book's param query.\n"
+            + "        description: Book's author. Optional.\n"
             + "        schema:\n"
             + "          type: string\n"
             + "      - name: isbn\n"
             + "        in: query\n"
-            + "        description: Book's param query.\n"
+            + "        description: Book's isbn. Optional.\n"
             + "        schema:\n"
             + "          type: string\n"
             + "      responses:\n"
@@ -167,7 +167,7 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "      properties:\n"
             + "        title:\n"
             + "          type: string\n"
-            + "          description: Book's title. Optional.\n"
+            + "          description: Book's title.\n"
             + "        author:\n"
             + "          type: string\n"
             + "          description: Book's author. Optional.\n"

modules/jooby-openapi/src/test/java/issues/i3729/api/BookQuery.java

@@ -8,7 +8,7 @@
 /**
  * Query books by complex filters.
  *
- * @param title Book's title. Optional.
+ * @param title Book's title.
  * @param author Book's author. Optional.
  * @param isbn Book's isbn. Optional.
  */

modules/jooby-openapi/src/test/java/javadoc/JavaDocParserTest.java

@@ -65,13 +65,9 @@ public void apiDoc() throws Exception {
               method -> {
                 assertEquals("Search database.", method.getSummary());
                 assertEquals("Search DB", method.getDescription());
-                assertEquals(
-                    "Filter query. Works like internal filter.",
-                    method.getParameterDoc("fq", "javadoc.input.QueryBeanDoc"));
-                assertEquals(
-                    "Offset, used for paging.",
-                    method.getParameterDoc("offset", "javadoc.input.QueryBeanDoc"));
-                assertNull(method.getParameterDoc("limit", "javadoc.input.QueryBeanDoc"));
+                assertNull(method.getParameterDoc("fq"));
+                assertNull(method.getParameterDoc("offset"));
+                assertNull(method.getParameterDoc("limit"));
                 assertNull(method.getReturnDoc());
               });
 
@@ -82,12 +78,8 @@ public void apiDoc() throws Exception {
               method -> {
                 assertEquals("Record database.", method.getSummary());
                 assertNull(method.getDescription());
-                assertEquals(
-                    "Person id. Unique person identifier.",
-                    method.getParameterDoc("id", "javadoc.input.RecordBeanDoc"));
-                assertEquals(
-                    "Person name. Example: edgar.",
-                    method.getParameterDoc("name", "javadoc.input.RecordBeanDoc"));
+                assertNull(method.getParameterDoc("id"));
+                assertNull(method.getParameterDoc("name"));
               });
 
           withMethod(