WIP: openapi: javadoc for script/lambda routes

- WIP

Author: jknack

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

@@ -24,6 +24,7 @@
 public class ClassDoc extends JavaDocNode {
   private final Map<String, FieldDoc> fields = new LinkedHashMap<>();
   private final Map<String, MethodDoc> methods = new LinkedHashMap<>();
+  private final Map<String, MethodDoc> scripts = new LinkedHashMap<>();
   private final List<Server> servers;
   private final List<Contact> contact;
   private final List<License> license;
@@ -160,6 +161,10 @@ public void addMethod(MethodDoc method) {
     this.methods.put(toMethodSignature(method), method);
   }
 
+  public void addScript(String pattern, MethodDoc method) {
+    this.scripts.put(pattern, method);
+  }
+
   public void addField(FieldDoc field) {
     this.fields.put(field.getName(), field);
   }
@@ -172,6 +177,10 @@ public Optional<MethodDoc> getMethod(String name, List<String> parameterNames) {
     return Optional.ofNullable(methods.get(toMethodSignature(name, parameterNames)));
   }
 
+  public Optional<MethodDoc> getScript(String pattern) {
+    return Optional.ofNullable(scripts.get(pattern));
+  }
+
   private String toMethodSignature(MethodDoc method) {
     return toMethodSignature(method.getName(), method.getParameterNames());
   }

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

@@ -22,6 +22,8 @@
 import com.puppycrawl.tools.checkstyle.JavaParser;
 import com.puppycrawl.tools.checkstyle.api.DetailAST;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
+import com.puppycrawl.tools.checkstyle.utils.XpathUtil;
+import io.jooby.Router;
 
 public class JavaDocParser {
 
@@ -57,6 +59,7 @@ public Map<String, ClassDoc> traverse(DetailAST tree) {
           counter.addAndGet(comment == JavaDocNode.EMPTY_AST ? 0 : 1);
           var classDoc = new ClassDoc(this, scope, comment);
 
+          // MVC routes
           traverse(
               scope,
               tokens(TokenTypes.VARIABLE_DEF, TokenTypes.METHOD_DEF),
@@ -72,10 +75,37 @@ public Map<String, ClassDoc> traverse(DetailAST tree) {
                   }
                 }
               });
-
-          if (classDoc.isRecord()) {
-            // complement with record parameter
+          // Script routes
+          for (var script :
+              tree(scope)
+                  .filter(tokens(TokenTypes.METHOD_CALL))
+                  // Test for HTTP method name
+                  .filter(
+                      it ->
+                          tree(it)
+                              .filter(tokens(TokenTypes.IDENT))
+                              .anyMatch(e -> Router.METHODS.contains(e.getText().toUpperCase())))
+                  .toList()) {
+            var scriptComment =
+                children(script)
+                    .filter(tokens(TokenTypes.BLOCK_COMMENT_BEGIN))
+                    .findFirst()
+                    .orElse(null);
+            if (scriptComment != null) {
+              // ELIST -> EXPR -> STRING_LITERAL
+              children(script)
+                  .filter(tokens(TokenTypes.ELIST))
+                  .findFirst()
+                  .flatMap(it -> children(it).filter(tokens(TokenTypes.EXPR)).findFirst())
+                  .flatMap(it -> children(it).filter(tokens(TokenTypes.STRING_LITERAL)).findFirst())
+                  .map(XpathUtil::getTextAttributeValue)
+                  .ifPresent(
+                      pattern -> {
+                        classDoc.addScript(pattern, new MethodDoc(this, script, scriptComment));
+                      });
+            }
           }
+
           if (counter.get() > 0) {
             classes.put(classDoc.getName(), classDoc);
           }

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

@@ -24,6 +24,37 @@
 
 public class JavaDocParserTest {
 
+  @Test
+  public void scriptDoc() throws Exception {
+    withDoc(
+        javadoc.input.ScriptApp.class,
+        doc -> {
+          assertEquals("ScriptApp", doc.getSimpleName());
+          assertEquals("javadoc.input.ScriptApp", doc.getName());
+          assertEquals("Script App.", doc.getSummary());
+          assertEquals("Some description.", doc.getDescription());
+
+          withScript(
+              doc,
+              "/static",
+              method -> {
+                assertEquals("This is a static path.", method.getSummary());
+                assertEquals("No parameters", method.getDescription());
+                assertEquals("Request Path.", method.getReturnDoc());
+              });
+
+          withScript(
+              doc,
+              "/path/{id}",
+              method -> {
+                assertEquals("Path param.", method.getSummary());
+                assertNull(method.getDescription());
+                assertEquals("Some value.", method.getReturnDoc());
+                assertEquals("Path ID.", method.getParameterDoc("id"));
+              });
+        });
+  }
+
   @Test
   public void apiDoc() throws Exception {
     withDoc(
@@ -258,6 +289,12 @@ private void withMethod(
     consumer.accept(method.get());
   }
 
+  private void withScript(ClassDoc doc, String pattern, Consumer<MethodDoc> consumer) {
+    var method = doc.getScript(pattern);
+    assertTrue(method.isPresent());
+    consumer.accept(method.get());
+  }
+
   private void withField(ClassDoc doc, String name, Consumer<FieldDoc> consumer) {
     var method = doc.getField(name);
     assertTrue(method.isPresent());

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

@@ -9,7 +9,7 @@
 import java.io.IOException;
 import java.nio.file.Path;
 import java.nio.file.Paths;
-import javadoc.input.ApiDoc;
+import javadoc.input.ScriptApp;
 
 import com.puppycrawl.tools.checkstyle.AstTreeStringPrinter;
 import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
@@ -25,7 +25,7 @@ public static void main(String[] args) throws CheckstyleException, IOException {
             .resolve("java");
     var stringAst =
         AstTreeStringPrinter.printJavaAndJavadocTree(
-            baseDir.resolve(toPath(ApiDoc.class)).toFile());
+            baseDir.resolve(toPath(ScriptApp.class)).toFile());
     System.out.println(stringAst);
   }
 

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

@@ -0,0 +1,38 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package javadoc.input;
+
+import io.jooby.Context;
+import io.jooby.Jooby;
+
+/** Script App. Some description. */
+public class ScriptApp extends Jooby {
+  {
+    // Ignored
+    /*
+     * This is a static path. No parameters
+     *
+     * @return Request Path.
+     */
+    get(
+        "/static",
+        ctx -> {
+          // Ignored.
+          return ctx.getRequestPath();
+          // Ignored
+        });
+
+    // Ignored
+    /*
+     * Path param.
+     *
+     * @param id Path ID.
+     * @return Some value.
+     */
+    // Ignored
+    get("/path/{id}", Context::getRequestPath);
+  }
+}