open-api: add @tag javadoc support

- ref #3729

Author: jknack

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

@@ -33,6 +33,7 @@
 import io.swagger.v3.oas.models.media.ObjectSchema;
 import io.swagger.v3.oas.models.media.Schema;
 import io.swagger.v3.oas.models.parameters.Parameter;
+import io.swagger.v3.oas.models.tags.Tag;
 import jakarta.inject.Named;
 import jakarta.inject.Provider;
 
@@ -279,6 +280,7 @@ public static List<OperationExt> parse(ParserContext ctx, String prefix, Type ty
                 doc -> {
                   operationExt.setPathDescription(doc.getDescription());
                   operationExt.setPathSummary(doc.getSummary());
+                  tags(doc.getTags()).forEach(operationExt::addTag);
                   if (!doc.getExtensions().isEmpty()) {
                     operationExt.setPathExtensions(doc.getExtensions());
                   }
@@ -296,6 +298,7 @@ public static List<OperationExt> parse(ParserContext ctx, String prefix, Type ty
                             if (!methodDoc.getExtensions().isEmpty()) {
                               operationExt.setExtensions(methodDoc.getExtensions());
                             }
+                            tags(methodDoc.getTags()).forEach(operationExt::addTag);
                             // Parameters
                             for (var parameterName : parameterNames) {
                               var paramExt =
@@ -343,6 +346,17 @@ public static List<OperationExt> parse(ParserContext ctx, String prefix, Type ty
     return result;
   }
 
+  private static List<Tag> tags(Map<String, String> tags) {
+    List<Tag> result = new ArrayList<>();
+    for (var tagNode : tags.entrySet()) {
+      var tag = new Tag();
+      tag.setName(tagNode.getKey());
+      tag.setDescription(tagNode.getValue());
+      result.add(tag);
+    }
+    return result;
+  }
+
   private static Map<String, MethodNode> methods(ParserContext ctx, ClassNode node) {
     Map<String, MethodNode> methods = new LinkedHashMap<>();
     if (node.superName != null && !node.superName.equals(TypeFactory.OBJECT.getInternalName())) {

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

@@ -6,27 +6,27 @@
 package io.jooby.internal.openapi.javadoc;
 
 import static io.jooby.internal.openapi.javadoc.JavaDocSupport.*;
+import static io.jooby.internal.openapi.javadoc.JavaDocSupport.javadocToken;
 
 import java.util.*;
 import java.util.function.Predicate;
 
-import com.fasterxml.jackson.core.JsonProcessingException;
 import com.puppycrawl.tools.checkstyle.DetailNodeTreeStringPrinter;
 import com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser;
 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.utils.JavadocUtil;
-import io.swagger.util.Yaml;
 
 public class JavaDocNode {
   private static final Predicate<DetailNode> JAVADOC_TAG =
-      JavaDocSupport.javadocToken(JavadocTokenTypes.JAVADOC_TAG);
+      javadocToken(JavadocTokenTypes.JAVADOC_TAG);
 
   protected final JavaDocParser context;
   protected final DetailAST node;
   protected final DetailNode javadoc;
   private final Map<String, Object> extensions;
+  private final Map<String, String> tags;
 
   public JavaDocNode(JavaDocParser ctx, DetailAST node, DetailAST comment) {
     this(ctx, node, toJavaDocNode(comment));
@@ -38,14 +38,55 @@ protected JavaDocNode(JavaDocParser ctx, DetailAST node, DetailNode javadoc) {
     this.javadoc = javadoc;
     if (this.javadoc != EMPTY_NODE) {
       this.extensions = parseExtensions(this.javadoc);
+      this.tags = parseTags(this.javadoc);
     } else {
       this.extensions = Map.of();
+      this.tags = Map.of();
     }
   }
 
+  private Map<String, String> parseTags(DetailNode node) {
+    var result = new LinkedHashMap<String, String>();
+    for (var docTag : tree(node).filter(JAVADOC_TAG).toList()) {
+      var tag =
+          tree(docTag)
+              .filter(
+                  javadocToken(JavadocTokenTypes.CUSTOM_NAME)
+                      .and(it -> it.getText().equals("@tag")))
+              .findFirst()
+              .orElse(null);
+      if (tag != null) {
+        var tagText =
+            tree(docTag)
+                .filter(javadocToken(JavadocTokenTypes.DESCRIPTION))
+                .findFirst()
+                .map(it -> getText(List.of(it.getChildren()), false))
+                .orElse(null);
+        if (tagText != null) {
+          var dot = tagText.indexOf(".");
+          var tagName = tagText;
+          String tagDescription = null;
+          if (dot > 0) {
+            tagName = tagText.substring(0, dot);
+            if (dot + 1 < tagText.length()) {
+              tagDescription = tagText.substring(dot + 1).trim();
+              if (tagDescription.isBlank()) {
+                tagDescription = null;
+              }
+            }
+          }
+          if (!tagName.trim().isEmpty()) {
+            result.put(tagName, tagDescription);
+          }
+        }
+      }
+    }
+    return result;
+  }
+
   private Map<String, Object> parseExtensions(DetailNode node) {
     var values = new ArrayList<String>();
-    for (var tag : tree(node).filter(javadocToken(JavadocTokenTypes.JAVADOC_TAG)).toList()) {
+    for (var tag : tree(node).filter(JAVADOC_TAG).toList()) {
       var extension =
           tree(tag)
               .filter(
@@ -105,6 +146,10 @@ public String getSummary() {
     return string.isEmpty() ? null : string;
   }
 
+  public Map<String, String> getTags() {
+    return tags;
+  }
+
   public String getDescription() {
     var text = getText();
     var summary = getSummary();
@@ -257,16 +302,4 @@ public boolean hasChildren() {
           return false;
         }
       };
-
-  public static void main(String[] args) throws JsonProcessingException {
-    var badges =
-        Yaml.mapper()
-            .readValue(
-                "x-badges:\n"
-                    + "        - name: 'Beta'\n"
-                    + "          position: before\n"
-                    + "          color: purple",
-                Map.class);
-    System.out.println(badges);
-  }
 }

modules/jooby-openapi/src/main/java/io/jooby/openapi/OpenAPIGenerator.java

@@ -221,16 +221,16 @@ public String toString(OpenAPIGenerator tool, OpenAPI result) {
       Optional.ofNullable(operation.getPathExtensions()).ifPresent(pathItem::setExtensions);
 
       // global tags
-      operation.getGlobalTags().forEach(tag -> globalTags.put(tag.getName(), tag));
+      operation
+          .getGlobalTags()
+          .forEach(
+              tag -> {
+                if (tag.getDescription() != null || tag.getExtensions() != null) {
+                  globalTags.put(tag.getName(), tag);
+                }
+              });
     }
-    globalTags
-        .values()
-        .forEach(
-            tag -> {
-              if (tag.getDescription() != null || tag.getExtensions() != null) {
-                openapi.addTagsItem(tag);
-              }
-            });
+    globalTags.values().forEach(openapi::addTagsItem);
     openapi.setOperations(operations);
     openapi.setPaths(paths);
 

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

@@ -23,12 +23,21 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "  x-logo:\n"
             + "    url: https://redocly.github.io/redoc/museum-logo.png\n"
             + "    altText: Museum logo\n"
+            + "tags:\n"
+            + "- name: Library\n"
+            + "  description: Access to all books.\n"
+            + "- name: Author\n"
+            + "  description: Oxxx\n"
             + "paths:\n"
             + "  /api/library/{isbn}:\n"
             + "    summary: Library API.\n"
             + "    description: \"Contains all operations for creating, updating and fetching"
             + " books.\"\n"
             + "    get:\n"
+            + "      tags:\n"
+            + "      - Library\n"
+            + "      - Book\n"
+            + "      - Author\n"
             + "      summary: Find a book by isbn.\n"
             + "      operationId: bookByIsbn\n"
             + "      parameters:\n"
@@ -49,11 +58,37 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "          description: \"Not Found: If a book doesn't exist.\"\n"
             + "        \"400\":\n"
             + "          description: \"Bad Request: For bad ISBN code.\"\n"
+            + "  /api/library/{id}:\n"
+            + "    summary: Library API.\n"
+            + "    description: \"Contains all operations for creating, updating and fetching"
+            + " books.\"\n"
+            + "    get:\n"
+            + "      tags:\n"
+            + "      - Library\n"
+            + "      - Author\n"
+            + "      summary: Author by Id.\n"
+            + "      operationId: author\n"
+            + "      parameters:\n"
+            + "      - name: id\n"
+            + "        in: path\n"
+            + "        description: ID.\n"
+            + "        required: true\n"
+            + "        schema:\n"
+            + "          type: string\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: An author\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                $ref: \"#/components/schemas/Author\"\n"
             + "  /api/library:\n"
             + "    summary: Library API.\n"
             + "    description: \"Contains all operations for creating, updating and fetching"
             + " books.\"\n"
             + "    get:\n"
+            + "      tags:\n"
+            + "      - Library\n"
             + "      summary: Query books.\n"
             + "      operationId: query\n"
             + "      parameters:\n"
@@ -86,6 +121,9 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "        position: before\n"
             + "        color: purple\n"
             + "    post:\n"
+            + "      tags:\n"
+            + "      - Library\n"
+            + "      - Author\n"
             + "      summary: Creates a new book.\n"
             + "      description: Book can be created or updated.\n"
             + "      operationId: createBook\n"
@@ -105,6 +143,23 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "                $ref: \"#/components/schemas/Book\"\n"
             + "components:\n"
             + "  schemas:\n"
+            + "    Author:\n"
+            + "      type: object\n"
+            + "      properties:\n"
+            + "        ssn:\n"
+            + "          type: string\n"
+            + "          description: Social security number.\n"
+            + "        name:\n"
+            + "          type: string\n"
+            + "          description: Author's name.\n"
+            + "        address:\n"
+            + "          $ref: \"#/components/schemas/Address\"\n"
+            + "        books:\n"
+            + "          uniqueItems: true\n"
+            + "          type: array\n"
+            + "          description: Published books.\n"
+            + "          items:\n"
+            + "            $ref: \"#/components/schemas/Book\"\n"
             + "    BookQuery:\n"
             + "      type: object\n"
             + "      properties:\n"
@@ -165,24 +220,7 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "          type: array\n"
             + "          items:\n"
             + "            $ref: \"#/components/schemas/Author\"\n"
-            + "      description: Book model.\n"
-            + "    Author:\n"
-            + "      type: object\n"
-            + "      properties:\n"
-            + "        ssn:\n"
-            + "          type: string\n"
-            + "          description: Social security number.\n"
-            + "        name:\n"
-            + "          type: string\n"
-            + "          description: Author's name.\n"
-            + "        address:\n"
-            + "          $ref: \"#/components/schemas/Address\"\n"
-            + "        books:\n"
-            + "          uniqueItems: true\n"
-            + "          type: array\n"
-            + "          description: Published books.\n"
-            + "          items:\n"
-            + "            $ref: \"#/components/schemas/Book\"\n",
+            + "      description: Book model.\n",
         result.toYaml());
   }
 }

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

@@ -15,6 +15,8 @@
  * Library API.
  *
  * <p>Contains all operations for creating, updating and fetching books.
+ *
+ * @tag Library. Access to all books.
  */
 @Path("/api/library")
 public class LibraryApi {
@@ -26,12 +28,26 @@ public class LibraryApi {
    * @return A matching book.
    * @throws NotFoundException <code>404</code> If a book doesn't exist.
    * @throws BadRequestException <code>400</code> For bad ISBN code.
+   * @tag Book
+   * @tag Author
    */
   @GET("/{isbn}")
   public Book bookByIsbn(@PathParam String isbn) throws NotFoundException, BadRequestException {
     return new Book();
   }
 
+  /**
+   * Author by Id.
+   *
+   * @param id ID.
+   * @return An author
+   * @tag Author. Oxxx
+   */
+  @GET("/{id}")
+  public Author author(@PathParam String id) {
+    return new Author();
+  }
+
   /**
    * Query books.
    *
@@ -53,6 +69,7 @@ public List<Book> query(@QueryParam BookQuery query) {
    *
    * @param book Book to create.
    * @return Saved book.
+   * @tag Author
    */
   @POST
   public Book createBook(Book book) {

modules/jooby-openapi/src/test/java/javadoc/input/ApiDoc.java

@@ -21,6 +21,7 @@
  * @x-badges.name Beta
  * @x-badges.position before
  * @x-badges.color purple
+ * @tag ApiTag
  */
 @Path("/api")
 public class ApiDoc {