open-api: document usage

jknack · jknack · commit f9104d3d7929 · 2025-08-03T19:16:38.000-03:00
- add few more tags - #3729
diff --git a/docs/asciidoc/modules/openapi.adoc b/docs/asciidoc/modules/openapi.adoc
@@ -2,7 +2,7 @@
 
 This module helps automating the generation of API documentation using Jooby projects. jooby-openapi works by examining an application at *build* time to infer API semantics based on byte code and optional annotations.
 
-Automatically generates documentation in JSON/YAML format APIs. This documentation can be completed by comments using swagger-api annotations.
+Automatically generates documentation in JSON/YAML format APIs. This documentation can be completed by javadoc comments or using swagger-api annotations.
 
 This library supports:
 
@@ -148,12 +148,20 @@ The OpenAPI generator works exactly the same for MVC routes (a.k.a Controller):
 {
   install(new OpenAPIModule());
 
-  mvc(new Pets());
+  mvc(new Pets_());
 }
 
+/**
+* Pet Library.
+*/
 @Path("/pets")
 public class Pets {
   
+  /**
+   * List pets.
+   * 
+   * @return All pets.
+   */
   @GET
   public List<Pet> list() {
     ...
@@ -168,7 +176,7 @@ public class Pets {
 {
   install(OpenAPIModule())
 
-  mvc(new MyController())
+  mvc(Pets_())
 }
 
 @Path("/pets")
@@ -185,9 +193,184 @@ class Pets {
 The Maven plugin and Gradle task provide two filter properties `includes` and `excludes`. These
 properties filter routes by their path pattern. The filter is a regular expression.
 
+=== JavaDoc comments
+
+Parsing of JavaDoc comment is supported on Java MVC/Controller.
+
+.Java
+[source,java]
+----
+
+/**
+* My Library.
+* @version 5.4.1
+* @tag Books. All about books.
+* @server.url https://books.api.com
+* @server.description Production
+* @x-logo https://my.api.com/logo.png
+*/
+public class App {
+  {
+    mvc(new Books_());
+    install(new OpenAPIModule());
+  }
+}
+/**
+ * Books operations.
+ * @tag Books  
+ */
+@Path("/api/books")
+public class Books {
+  /**
+   * Query and filter books.
+    * 
+   * @param query Book filter.
+   * @return List of matching books.
+   */
+  public List<Book> query(@QueryParam BookQuery query) {
+     ....
+  }
+  /**
+   * Find a book by ISBN.
+   * 
+   * @param isbn ISBN code.
+   * @return A book.
+   * @throws BookNotFoundException When a book doesn't exist. <code>404</code> 
+   */
+  public Book bookByIsbn(@PathParam String isbn) {
+    
+  }
+}
+
+/**
+ * Book query.
+ * 
+ * @type Book type.
+ * @aga Book age.
+ */
+public record BookQuery(BookType type, int age) {}
+
+/**
+ * Books can be broadly categorized into fiction and non-fiction
+ */
+public enum BookType {
+  /**
+  * Fiction includes genres like fantasy, science fiction, romance, and mystery.
+  */
+  Fiction,
+  /**
+  * Non-fiction encompasses genres like history, biography, and self-help.
+  */
+  NonFiction
+}
+----
+
+A JavaDoc comment is split into:
+
+- summary: Everything before the first `.` or `<p>` paragraph
+- description: Everything after the first `.` or `<p>` paragraph
+
+Whitespaces (including new lines) are ignored. To introduce a new line, you must use a `<p>`.
+
+==== Supported OpenAPI tags
+
+[cols="3,1,1,1,4"]
+|===
+| Tag | Main | Controller | Method | Description
+
+|@version 4.0.4
+| [x]
+|
+|
+|
+
+|@contact.name
+|[x]
+|
+|
+|
+
+|@contact.url
+|[x]
+|
+|
+|
+
+|@contact.email
+|[x]
+|
+|
+|
+
+|@license.name
+|[x]
+|
+|
+|
+
+|@license.url
+|[x]
+|
+|
+|
+
+|@server.description
+|[x]
+|
+|
+|
+
+|@x-
+|[x]
+|[x]
+|[x]
+|Tag starting with `x-` is considered an extension
+
+|@tag.name
+|[x]
+|[x]
+|[x]
+|Tag name
+
+|@tag.description
+|[x]
+|[x]
+|[x]
+|Tag Description
+
+|@tag
+|[x]
+|[x]
+|[x]
+|Shortcut for previous `@tag.name` and `@tag.description`. The tag name is everything before `.`
+
+|@param <name>
+|
+|
+|[x]
+|Operation parameter
+
+|@return
+|
+|
+|[x]
+|Operation default response
+
+|@throws
+|
+|
+|[x]
+|Additional non-success responses types. The HTTP response code is taken from `<code>{number}</code>`, or set to `500` error.
+
+|===
+
+This feature is only available for Java MVC/controller routes. There are plans to support lambda
+routes on Java. Kotlin source code is not supported.
+
+
 === Annotations
 
-To produces a better documentation this plugin depends on some OpenAPI annotations. To use them, you
+To produce a better documentation, this plugin depends on some OpenAPI annotations. To use them, you
 need to add a dependency to your project:
 
 [dependency, artifactId="swagger-annotations"]
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/ClassDoc.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/ClassDoc.java
@@ -17,12 +17,16 @@
 import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.License;
 import io.swagger.v3.oas.models.servers.Server;
 
 public class ClassDoc extends JavaDocNode {
   private final Map<String, FieldDoc> fields = new LinkedHashMap<>();
   private final Map<String, MethodDoc> methods = new LinkedHashMap<>();
   private final List<Server> servers;
+  private final List<Contact> contact;
+  private final List<License> license;
 
   public ClassDoc(JavaDocParser ctx, DetailAST node, DetailAST javaDoc) {
     super(ctx, node, javaDoc);
@@ -32,12 +36,22 @@ public ClassDoc(JavaDocParser ctx, DetailAST node, DetailAST javaDoc) {
       defaultEnumMembers();
     }
     this.servers = JavaDocTag.servers(this.javadoc);
+    this.contact = JavaDocTag.contacts(this.javadoc);
+    this.license = JavaDocTag.license(this.javadoc);
   }
 
   public List<Server> getServers() {
     return servers;
   }
 
+  public List<Contact> getContact() {
+    return contact;
+  }
+
+  public List<License> getLicense() {
+    return license;
+  }
+
   public String getVersion() {
     return tree(javadoc)
         .filter(javadocToken(JavadocTokenTypes.VERSION_LITERAL))
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocTag.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocTag.java
@@ -10,13 +10,16 @@
 import static io.jooby.internal.openapi.javadoc.JavaDocSupport.children;
 
 import java.util.*;
+import java.util.function.Function;
 import java.util.function.Predicate;
 
 import com.puppycrawl.tools.checkstyle.api.DetailNode;
 import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
 import io.jooby.SneakyThrows.Consumer2;
 import io.jooby.SneakyThrows.Consumer3;
 import io.jooby.StatusCode;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.License;
 import io.swagger.v3.oas.models.servers.Server;
 import io.swagger.v3.oas.models.tags.Tag;
 
@@ -27,36 +30,77 @@ public class JavaDocTag {
       CUSTOM_TAG.and(it -> it.getText().startsWith("@tag.") || it.getText().equals("@tag"));
   private static final Predicate<DetailNode> SERVER =
       CUSTOM_TAG.and(it -> it.getText().startsWith("@server."));
+  private static final Predicate<DetailNode> CONTACT =
+      CUSTOM_TAG.and(it -> it.getText().startsWith("@contact."));
+  private static final Predicate<DetailNode> LICENSE =
+      CUSTOM_TAG.and(it -> it.getText().startsWith("@license."));
   private static final Predicate<DetailNode> EXTENSION =
       CUSTOM_TAG.and(it -> it.getText().startsWith("@x-"));
   private static final Predicate<DetailNode> THROWS =
       it -> tree(it).anyMatch(javadocToken(JavadocTokenTypes.THROWS_LITERAL));
 
-  @SuppressWarnings("unchecked")
   public static List<Server> servers(DetailNode node) {
+    return openApiComponent(
+        node,
+        SERVER,
+        "server",
+        hash -> {
+          var server = new Server();
+          server.setDescription((String) hash.get("description"));
+          server.setUrl((String) hash.get("url"));
+          return server;
+        });
+  }
+
+  public static List<Contact> contacts(DetailNode node) {
+    return openApiComponent(
+        node,
+        CONTACT,
+        "contact",
+        hash -> {
+          var item = new Contact();
+          item.setName((String) hash.get("name"));
+          item.setUrl((String) hash.get("url"));
+          item.setEmail((String) hash.get("email"));
+          return item;
+        });
+  }
+
+  public static List<License> license(DetailNode node) {
+    return openApiComponent(
+        node,
+        LICENSE,
+        "license",
+        hash -> {
+          var item = new License();
+          item.setName((String) hash.get("name"));
+          item.setUrl((String) hash.get("url"));
+          return item;
+        });
+  }
+
+  private static <T> List<T> openApiComponent(
+      DetailNode node, Predicate<DetailNode> filter, String path, Function<Map<?, ?>, T> mapper) {
     var values = new ArrayList<String>();
     javaDocTag(
         node,
-        SERVER,
+        filter,
         (tag, value) -> {
           values.add(tag.getText().substring(1));
           values.add(value);
         });
-    var result = new ArrayList<Server>();
+    var result = new ArrayList<T>();
     if (!values.isEmpty()) {
-      var serverMap = MiniYamlDocParser.parse(values);
-      var servers = serverMap.get("server");
-      if (!(servers instanceof List<?>)) {
-        servers = List.of(servers);
+      var output = MiniYamlDocParser.parse(values);
+      var itemList = output.get(path);
+      if (!(itemList instanceof List<?>)) {
+        itemList = List.of(itemList);
       }
-      ((List) servers)
+      ((List) itemList)
           .forEach(
               it -> {
                 if (it instanceof Map<?, ?> hash) {
-                  var server = new Server();
-                  server.setDescription((String) hash.get("description"));
-                  server.setUrl((String) hash.get("url"));
-                  result.add(server);
+                  result.add(mapper.apply(hash));
                 }
               });
     }
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/openapi/OpenAPIGenerator.java b/modules/jooby-openapi/src/main/java/io/jooby/openapi/OpenAPIGenerator.java
@@ -168,6 +168,8 @@ public String toString(OpenAPIGenerator tool, OpenAPI result) {
                   info.setExtensions(doc.getExtensions());
                 }
                 doc.getServers().forEach(openapi::addServersItem);
+                doc.getContact().forEach(info::setContact);
+                doc.getLicense().forEach(info::setLicense);
               });
     }
 
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
@@ -19,6 +19,13 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "info:\n"
             + "  title: Library API.\n"
             + "  description: \"Available data: Books and authors.\"\n"
+            + "  contact:\n"
+            + "    name: Jooby\n"
+            + "    url: https://jooby.io\n"
+            + "    email: support@jooby.io\n"
+            + "  license:\n"
+            + "    name: Apache\n"
+            + "    url: https://jooby.io/LICENSE\n"
             + "  version: 4.0.0\n"
             + "  x-logo:\n"
             + "    url: https://redocly.github.io/redoc/museum-logo.png\n"
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/AppLibrary.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/AppLibrary.java

Original file line number	Diff line number	Diff line change
`@@ -168,6 +168,8 @@ public String toString(OpenAPIGenerator tool, OpenAPI result) {`
`168`	`168`	`info.setExtensions(doc.getExtensions());`
`169`	`169`	`}`
`170`	`170`	`doc.getServers().forEach(openapi::addServersItem);`
	`171`	`+ doc.getContact().forEach(info::setContact);`
	`172`	`+ doc.getLicense().forEach(info::setLicense);`
`171`	`173`	`});`
`172`	`174`	`}`
`173`	`175`