open-api: parse javadoc #3729

- parse @server

Author: jknack

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

@@ -17,10 +17,12 @@
 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.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;
 
   public ClassDoc(JavaDocParser ctx, DetailAST node, DetailAST javaDoc) {
     super(ctx, node, javaDoc);
@@ -29,6 +31,11 @@ public ClassDoc(JavaDocParser ctx, DetailAST node, DetailAST javaDoc) {
     } else if (isEnum()) {
       defaultEnumMembers();
     }
+    this.servers = JavaDocTag.servers(this.javadoc);
+  }
+
+  public List<Server> getServers() {
+    return servers;
   }
 
   public String getVersion() {

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

@@ -17,17 +17,51 @@
 import io.jooby.SneakyThrows.Consumer2;
 import io.jooby.SneakyThrows.Consumer3;
 import io.jooby.StatusCode;
+import io.swagger.v3.oas.models.servers.Server;
 
 public class JavaDocTag {
   private static final Predicate<DetailNode> CUSTOM_TAG =
       javadocToken(JavadocTokenTypes.CUSTOM_NAME);
   private static final Predicate<DetailNode> TAG =
       CUSTOM_TAG.and(it -> it.getText().equals("@tag"));
+  private static final Predicate<DetailNode> SERVER =
+      CUSTOM_TAG.and(it -> it.getText().startsWith("@server."));
   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) {
+    var values = new ArrayList<String>();
+    javaDocTag(
+        node,
+        SERVER,
+        (tag, value) -> {
+          values.add(tag.getText().substring(1));
+          values.add(value);
+        });
+    List<Server> result = new ArrayList<>();
+    if (!values.isEmpty()) {
+      var serverMap = ExtensionJavaDocParser.parse(values);
+      var servers = serverMap.get("server");
+      if (!(servers instanceof List<?>)) {
+        servers = List.of(servers);
+      }
+      ((List) servers)
+          .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);
+                }
+              });
+    }
+    return result;
+  }
+
   public static Map<StatusCode, ThrowsDoc> throwList(DetailNode node) {
     var result = new LinkedHashMap<StatusCode, ThrowsDoc>();
     javaDocTag(

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

@@ -167,6 +167,7 @@ public String toString(OpenAPIGenerator tool, OpenAPI result) {
                 if (!doc.getExtensions().isEmpty()) {
                   info.setExtensions(doc.getExtensions());
                 }
+                doc.getServers().forEach(openapi::addServersItem);
               });
     }
 

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

@@ -23,6 +23,8 @@ public void shouldGenerateDoc(OpenAPIResult result) {
             + "  x-logo:\n"
             + "    url: https://redocly.github.io/redoc/museum-logo.png\n"
             + "    altText: Museum logo\n"
+            + "servers:\n"
+            + "- url: https://api.fake-museum-example.com/v1\n"
             + "tags:\n"
             + "- name: Library\n"
             + "  description: Access to all books.\n"

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

@@ -15,6 +15,7 @@
  * <p>Available data: Books and authors.
  *
  * @version 4.0.0
+ * @server.url https://api.fake-museum-example.com/v1
  * @x-logo.url https://redocly.github.io/redoc/museum-logo.png
  * @x-logo.altText Museum logo
  */

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

@@ -37,6 +37,13 @@ public void apiDoc() throws Exception {
                   + " ante id vestibulum congue. Nam et tortor at magna tempor congue.",
               doc.getDescription());
 
+          var servers = doc.getServers();
+          assertEquals(2, servers.size());
+          assertEquals("https://api.example.com/v1", servers.get(0).getUrl());
+          assertEquals("Production server (uses live data)", servers.get(0).getDescription());
+          assertEquals("https://sandbox-api.example.com:8443/v1", servers.get(1).getUrl());
+          assertEquals("Sandbox server (uses test data)", servers.get(1).getDescription());
+
           withMethod(
               doc,
               "hello",

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

@@ -22,6 +22,10 @@
  * @x-badges.position before
  * @x-badges.color purple
  * @tag ApiTag
+ * @server.url https://api.example.com/v1
+ * @server.description Production server (uses live data)
+ * @server.url https://sandbox-api.example.com:8443/v1
+ * @server.description Sandbox server (uses test data)
  */
 @Path("/api")
 public class ApiDoc {