openapi: more clean up + support return doc + throws

jknack · jknack · commit d63792fd352f · 2025-07-31T19:58:46.000-03:00
- ref #3733
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/AnnotationParser.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/AnnotationParser.java
@@ -290,6 +290,7 @@ public static List<OperationExt> parse(ParserContext ctx, String prefix, Type ty
                           methodDoc -> {
                             operationExt.setSummary(methodDoc.getSummary());
                             operationExt.setDescription(methodDoc.getDescription());
+                            // Parameters
                             for (var parameterName : parameterNames) {
                               var paramExt =
                                   operationExt.getParameters().stream()
@@ -311,14 +312,21 @@ public static List<OperationExt> parse(ParserContext ctx, String prefix, Type ty
                                 }
                               }
                             }
-                            for (var parameter : operationExt.getParameters()) {
-                              var paramExt = (ParameterExt) parameter;
-                              var paramDoc =
-                                  methodDoc.getParameterDoc(
-                                      paramExt.getName(), paramExt.getContainerType());
-                              if (paramDoc != null) {
-                                paramExt.setDescription(paramDoc);
+                            // return types
+                            var defaultResponse = operationExt.getDefaultResponse();
+                            if (defaultResponse != null) {
+                              defaultResponse.setDescription(methodDoc.getReturnDoc());
+                            }
+                            for (var throwsDoc : methodDoc.getThrows().values()) {
+                              var response =
+                                  operationExt.getResponse(
+                                      Integer.toString(throwsDoc.getStatusCode().value()));
+                              if (response == null) {
+                                response =
+                                    operationExt.addResponse(
+                                        Integer.toString(throwsDoc.getStatusCode().value()));
                               }
+                              response.setDescription(throwsDoc.getText());
                             }
                           });
                 });
@@ -445,7 +453,7 @@ private static List<ParameterExt> routerArguments(
 
         if (paramType == ParamType.BODY) {
           RequestBodyExt body = new RequestBodyExt();
-          body.setRequired(required);
+          body.setRequired(true);
           body.setJavaType(javaType);
           requestBody.accept(body);
         } else if (paramType == ParamType.FORM) {
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RequestBodyExt.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RequestBodyExt.java
@@ -10,6 +10,7 @@
 import io.swagger.v3.oas.models.parameters.RequestBody;
 
 public class RequestBodyExt extends RequestBody {
+
   @JsonIgnore private String javaType;
 
   @JsonIgnore private String contentType = MediaType.JSON;
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RouteParser.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/RouteParser.java
@@ -47,6 +47,7 @@
 import io.jooby.Router;
 import io.jooby.SneakyThrows;
 import io.jooby.annotation.OpenApiRegister;
+import io.swagger.v3.core.util.Json;
 import io.swagger.v3.oas.models.media.ComposedSchema;
 import io.swagger.v3.oas.models.media.Content;
 import io.swagger.v3.oas.models.media.Schema;
@@ -171,11 +172,15 @@ private List<Parameter> checkParameters(ParserContext ctx, List<Parameter> param
           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(s);
+            p.setSchema(schemaNoDesc);
+            p.setDescription(parameter.getDescription());
 
             params.add(p);
           }
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/MethodDoc.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/MethodDoc.java
@@ -7,18 +7,81 @@
 
 import static io.jooby.internal.openapi.javadoc.JavaDocSupport.*;
 
-import java.util.ArrayList;
-import java.util.List;
+import java.util.*;
 import java.util.stream.Stream;
 
 import com.puppycrawl.tools.checkstyle.api.DetailAST;
 import com.puppycrawl.tools.checkstyle.api.DetailNode;
 import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+import io.jooby.StatusCode;
 
 public class MethodDoc extends JavaDocNode {
+
+  private Map<StatusCode, ThrowsDoc> throwList;
+
   public MethodDoc(JavaDocParser ctx, DetailAST node, DetailAST javadoc) {
     super(ctx, node, javadoc);
+    throwList = throwList(this.javadoc);
+  }
+
+  private Map<StatusCode, ThrowsDoc> throwList(DetailNode javadoc) {
+    var result = new LinkedHashMap<StatusCode, ThrowsDoc>();
+    for (var tag : tree(javadoc).filter(javadocToken(JavadocTokenTypes.JAVADOC_TAG)).toList()) {
+      var isThrows = tree(tag).anyMatch(javadocToken(JavadocTokenTypes.THROWS_LITERAL));
+      if (isThrows) {
+        var text =
+            tree(tag)
+                .filter(javadocToken(JavadocTokenTypes.DESCRIPTION))
+                .findFirst()
+                .map(it -> getText(List.of(it.getChildren()), true))
+                .orElse(null);
+        var statusCode =
+            tree(tag)
+                .filter(javadocToken(JavadocTokenTypes.DESCRIPTION))
+                .findFirst()
+                .flatMap(
+                    it ->
+                        tree(it)
+                            .filter(javadocToken(JavadocTokenTypes.HTML_TAG_NAME))
+                            .filter(tagName -> tagName.getText().equals("code"))
+                            .flatMap(
+                                tagName ->
+                                    backward(tagName)
+                                        .filter(javadocToken(JavadocTokenTypes.HTML_TAG))
+                                        .findFirst()
+                                        .stream())
+                            .flatMap(
+                                htmlTag ->
+                                    children(htmlTag)
+                                        .filter(javadocToken(JavadocTokenTypes.TEXT))
+                                        .findFirst()
+                                        .stream())
+                            .map(DetailNode::getText)
+                            .map(
+                                value -> {
+                                  try {
+                                    return Integer.parseInt(value);
+                                  } catch (NumberFormatException e) {
+                                    return null;
+                                  }
+                                })
+                            .filter(Objects::nonNull)
+                            .filter(code -> code >= 400 && code <= 600)
+                            .map(StatusCode::valueOf)
+                            .findFirst())
+                .orElse(null);
+        //        var className = tree(tag).filter(javadocToken(JavadocTokenTypes.CLASS_NAME))
+        //            .findFirst()
+        //            .map(DetailNode::getText)
+        //            .orElse(null);
+        if (statusCode != null) {
+          var throwsDoc = new ThrowsDoc(statusCode, text);
+          result.putIfAbsent(statusCode, throwsDoc);
+        }
+      }
+    }
+    return result;
   }
 
   MethodDoc(JavaDocParser ctx, DetailAST node, DetailNode javadoc) {
@@ -91,4 +154,8 @@ public String getReturnDoc() {
         .map(it -> getText(tree(it).toList(), true))
         .orElse(null);
   }
+
+  public Map<StatusCode, ThrowsDoc> getThrows() {
+    return throwList;
+  }
 }
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/ThrowsDoc.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/ThrowsDoc.java
@@ -0,0 +1,30 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal.openapi.javadoc;
+
+import io.jooby.StatusCode;
+
+public class ThrowsDoc {
+  private final String text;
+  private final StatusCode statusCode;
+
+  public ThrowsDoc(StatusCode statusCode, String text) {
+    this.statusCode = statusCode;
+    if (text == null) {
+      this.text = statusCode.reason();
+    } else {
+      this.text = statusCode.reason() + ": " + text;
+    }
+  }
+
+  public String getText() {
+    return text;
+  }
+
+  public StatusCode getStatusCode() {
+    return statusCode;
+  }
+}
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/ApiDocTest.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/ApiDocTest.java
@@ -37,34 +37,80 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "          type: string\n"
             + "      responses:\n"
             + "        \"200\":\n"
-            + "          description: Success\n"
+            + "          description: A matching book.\n"
             + "          content:\n"
             + "            application/json:\n"
             + "              schema:\n"
             + "                $ref: \"#/components/schemas/Book\"\n"
+            + "        \"404\":\n"
+            + "          description: \"Not Found: If a book doesn't exist.\"\n"
+            + "        \"400\":\n"
+            + "          description: \"Bad Request: For bad ISBN code.\"\n"
             + "  /api/library:\n"
             + "    summary: Library API.\n"
             + "    description: \"Contains all operations for creating, updating and fetching"
             + " books.\"\n"
+            + "    get:\n"
+            + "      summary: Query books.\n"
+            + "      operationId: query\n"
+            + "      parameters:\n"
+            + "      - name: title\n"
+            + "        in: query\n"
+            + "        description: Book's param query.\n"
+            + "        schema:\n"
+            + "          type: string\n"
+            + "      - name: author\n"
+            + "        in: query\n"
+            + "        description: Book's param query.\n"
+            + "        schema:\n"
+            + "          type: string\n"
+            + "      - name: isbn\n"
+            + "        in: query\n"
+            + "        description: Book's param query.\n"
+            + "        schema:\n"
+            + "          type: string\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: Matching books.\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                type: array\n"
+            + "                items:\n"
+            + "                  $ref: \"#/components/schemas/Book\"\n"
             + "    post:\n"
             + "      summary: Creates a new book.\n"
+            + "      description: Book can be created or updated.\n"
             + "      operationId: createBook\n"
             + "      requestBody:\n"
             + "        description: Book to create.\n"
             + "        content:\n"
             + "          application/json:\n"
             + "            schema:\n"
             + "              $ref: \"#/components/schemas/Book\"\n"
-            + "        required: false\n"
+            + "        required: true\n"
             + "      responses:\n"
             + "        \"200\":\n"
-            + "          description: Success\n"
+            + "          description: Saved book.\n"
             + "          content:\n"
             + "            application/json:\n"
             + "              schema:\n"
             + "                $ref: \"#/components/schemas/Book\"\n"
             + "components:\n"
             + "  schemas:\n"
+            + "    BookQuery:\n"
+            + "      type: object\n"
+            + "      properties:\n"
+            + "        title:\n"
+            + "          type: string\n"
+            + "          description: Book's title. Optional.\n"
+            + "        author:\n"
+            + "          type: string\n"
+            + "          description: Book's author. Optional.\n"
+            + "        isbn:\n"
+            + "          type: string\n"
+            + "          description: Book's isbn. Optional.\n"
+            + "      description: Query books by complex filters.\n"
             + "    Address:\n"
             + "      type: object\n"
             + "      properties:\n"
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/BookQuery.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/BookQuery.java
@@ -0,0 +1,15 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package issues.i3729.api;
+
+/**
+ * Query books by complex filters.
+ *
+ * @param title Book's title. Optional.
+ * @param author Book's author. Optional.
+ * @param isbn Book's isbn. Optional.
+ */
+public record BookQuery(String title, String author, String isbn) {}
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/LibraryApi.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/LibraryApi.java
@@ -5,10 +5,11 @@
  */
 package issues.i3729.api;
 
-import io.jooby.annotation.GET;
-import io.jooby.annotation.POST;
-import io.jooby.annotation.Path;
-import io.jooby.annotation.PathParam;
+import java.util.List;
+
+import io.jooby.annotation.*;
+import io.jooby.exception.BadRequestException;
+import io.jooby.exception.NotFoundException;
 
 /**
  * Library API.
@@ -22,16 +23,31 @@ public class LibraryApi {
    * Find a book by isbn.
    *
    * @param isbn Book isbn. Like IK-1900.
-   * @return A book
+   * @return A matching book.
+   * @throws NotFoundException <code>404</code> If a book doesn't exist.
+   * @throws BadRequestException <code>400</code> For bad ISBN code.
    */
   @GET("/{isbn}")
-  public Book bookByIsbn(@PathParam String isbn) {
+  public Book bookByIsbn(@PathParam String isbn) throws NotFoundException, BadRequestException {
     return new Book();
   }
 
+  /**
+   * Query books.
+   *
+   * @param query Book's param query.
+   * @return Matching books.
+   */
+  @GET
+  public List<Book> query(@QueryParam BookQuery query) {
+    return List.of(new Book());
+  }
+
   /**
    * Creates a new book.
    *
+   * <p>Book can be created or updated.
+   *
    * @param book Book to create.
    * @return Saved book.
    */
diff --git a/modules/jooby-openapi/src/test/java/javadoc/JavaDocParserTest.java b/modules/jooby-openapi/src/test/java/javadoc/JavaDocParserTest.java
@@ -133,7 +133,8 @@ public void shouldParseEnum() throws Exception {
           assertEquals("Enum summary.", doc.getSummary());
           assertEquals("Enum desc.", doc.getDescription());
           assertEquals(
-              "Enum summary.\n" + "  - Foo: Foo doc.\n" + "  - Bar: Bar doc.", doc.getText());
+              "Enum summary.\n" + "  - Foo: Foo doc.\n" + "  - Bar: Bar doc.",
+              doc.getEnumDescription(doc.getSummary()));
         });
   }
 
diff --git a/modules/jooby-openapi/src/test/java/javadoc/PrintAstTree.java b/modules/jooby-openapi/src/test/java/javadoc/PrintAstTree.java
@@ -9,10 +9,10 @@
 import java.io.IOException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
-import javadoc.input.NoDoc;
 
 import com.puppycrawl.tools.checkstyle.AstTreeStringPrinter;
 import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
+import issues.i3729.api.LibraryApi;
 
 public class PrintAstTree {
   public static void main(String[] args) throws CheckstyleException, IOException {
@@ -24,7 +24,8 @@ public static void main(String[] args) throws CheckstyleException, IOException {
             .resolve("test")
             .resolve("java");
     var stringAst =
-        AstTreeStringPrinter.printJavaAndJavadocTree(baseDir.resolve(toPath(NoDoc.class)).toFile());
+        AstTreeStringPrinter.printJavaAndJavadocTree(
+            baseDir.resolve(toPath(LibraryApi.class)).toFile());
     System.out.println(stringAst);
   }
 

Original file line number	Diff line number	Diff line change
`@@ -133,7 +133,8 @@ public void shouldParseEnum() throws Exception {`
`133`	`133`	`assertEquals("Enum summary.", doc.getSummary());`
`134`	`134`	`assertEquals("Enum desc.", doc.getDescription());`
`135`	`135`	`assertEquals(`
`136`		`- "Enum summary.\n" + " - Foo: Foo doc.\n" + " - Bar: Bar doc.", doc.getText());`
	`136`	`+ "Enum summary.\n" + " - Foo: Foo doc.\n" + " - Bar: Bar doc.",`
	`137`	`+ doc.getEnumDescription(doc.getSummary()));`
`137`	`138`	`});`
`138`	`139`	`}`
`139`	`140`