open-api: traverse mount/install instruction on lambda/script routes and documente all them

jknack · jknack · commit 3638d0c0e77a · 2025-08-06T10:32:55.000-03:00
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/OperationExt.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/OperationExt.java
@@ -211,6 +211,11 @@ public void setController(ClassNode controller) {
     this.controller = controller;
   }
 
+  @Override
+  public void setOperationId(String operationId) {
+    super.setOperationId(operationId);
+  }
+
   @JsonIgnore
   public List<AnnotationNode> getAllAnnotations() {
     return Stream.of(
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
@@ -65,22 +65,9 @@ public List<OperationExt> parse(ParserContext ctx, OpenAPIExt openapi) {
         Optional.ofNullable(ctx.getMainClass()).orElse(ctx.getRouter().getClassName());
     ClassNode application = ctx.classNode(Type.getObjectType(applicationName.replace(".", "/")));
 
-    // javadoc
-    var javaDoc = ctx.javadoc().parse(ctx.getRouter().getClassName());
-    for (OperationExt operation : operations) {
-      // Script/lambda
-      if (operation.getController() == null) {
-        javaDoc
-            .flatMap(doc -> doc.getScript(operation.getMethod(), operation.getPattern()))
-            .ifPresent(
-                scriptDoc -> {
-                  if (scriptDoc.getPath() != null) {
-                    JavaDocSetter.setPath(operation, scriptDoc.getPath());
-                  }
-                  JavaDocSetter.set(operation, scriptDoc);
-                });
-      }
-    }
+    // JavaDoc
+    addJavaDoc(ctx, ctx.getRouter().getClassName(), "", operations);
+
     // swagger/openapi:
     for (OperationExt operation : operations) {
       operation.setApplication(application);
@@ -116,6 +103,29 @@ public List<OperationExt> parse(ParserContext ctx, OpenAPIExt openapi) {
     return result;
   }
 
+  private static void addJavaDoc(
+      ParserContext ctx, String className, String prefix, List<OperationExt> operations) {
+    // javadoc
+    var offset = prefix == null || prefix.isEmpty() ? 0 : prefix.length();
+    var javaDoc = ctx.javadoc().parse(className);
+    for (OperationExt operation : operations) {
+      // Script/lambda
+      if (operation.getController() == null) {
+        javaDoc
+            .flatMap(
+                doc ->
+                    doc.getScript(operation.getMethod(), operation.getPattern().substring(offset)))
+            .ifPresent(
+                scriptDoc -> {
+                  if (scriptDoc.getPath() != null) {
+                    JavaDocSetter.setPath(operation, scriptDoc.getPath());
+                  }
+                  JavaDocSetter.set(operation, scriptDoc);
+                });
+      }
+    }
+  }
+
   private void checkResponses(ParserContext ctx, OperationExt operation) {
     // checkResponse(ctx, operation, 200, operation.getDefaultResponse());
     for (Map.Entry<String, ApiResponse> entry : operation.getResponses().entrySet()) {
@@ -607,7 +617,9 @@ private List<OperationExt> mountRouter(
       throw new UnsupportedOperationException(InsnSupport.toString(node));
     }
     ClassNode classNode = ctx.classNode(router);
-    return parse(ctx.newContext(router), prefix, classNode);
+    var operations = parse(ctx.newContext(router), prefix, classNode);
+    addJavaDoc(ctx, router.getClassName(), prefix, operations);
+    return operations;
   }
 
   private List<OperationExt> installApp(
@@ -632,7 +644,9 @@ private List<OperationExt> installApp(
       throw new UnsupportedOperationException(InsnSupport.toString(node));
     }
     ClassNode classNode = ctx.classNode(router);
-    return parse(ctx.newContext(router), prefix, classNode);
+    var operations = parse(ctx.newContext(router), prefix, classNode);
+    addJavaDoc(ctx, router.getClassName(), prefix, operations);
+    return operations;
   }
 
   private Type kotlinSupplier(ParserContext ctx, MethodInsnNode node, AbstractInsnNode ins) {
@@ -896,7 +910,8 @@ private OperationExt newRouteDescriptor(
         node.name.equals("apply")
             || node.name.equals("invoke")
             || node.name.startsWith("invoke$")
-            || node.name.contains("$lambda");
+            || node.name.contains("$lambda")
+            || node.name.startsWith("fake$");
     if (notSynthetic && !lambda) {
       operation.setOperationId(node.name);
     }
diff --git a/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocParser.java b/modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/javadoc/JavaDocParser.java
@@ -79,7 +79,7 @@ public Map<String, ClassDoc> traverse(DetailAST tree) {
                 }
               });
           // Script routes
-          scripts(scope, classDoc, null, null, new HashSet<>());
+          counter.addAndGet(scripts(scope, classDoc, null, null, new HashSet<>()));
 
           if (counter.get() > 0) {
             classes.put(classDoc.getName(), classDoc);
@@ -88,8 +88,9 @@ public Map<String, ClassDoc> traverse(DetailAST tree) {
     return classes;
   }
 
-  private void scripts(
+  private int scripts(
       DetailAST scope, ClassDoc classDoc, PathDoc pathDoc, String prefix, Set<DetailAST> visited) {
+    var counter = new AtomicInteger(0);
     for (var script : tree(scope).filter(tokens(TokenTypes.METHOD_CALL)).toList()) {
       if (visited.add(script)) {
         // Test for HTTP method name
@@ -106,11 +107,17 @@ private void scripts(
                 .filter(tokens(TokenTypes.BLOCK_COMMENT_BEGIN))
                 .findFirst()
                 .orElse(JavaDocNode.EMPTY_AST);
+        if (scriptComment != JavaDocNode.EMPTY_AST) {
+          counter.incrementAndGet();
+        }
         if (Router.METHODS.contains(callName.toUpperCase())) {
           pathLiteral(script)
               .ifPresent(
                   pattern -> {
                     var resolvedComment = resolveScriptComment(classDoc, script, scriptComment);
+                    if (scriptComment != resolvedComment.comment) {
+                      counter.incrementAndGet();
+                    }
                     var scriptDoc =
                         new ScriptDoc(
                             this,
@@ -138,6 +145,7 @@ private void scripts(
         }
       }
     }
+    return counter.get();
   }
 
   /**
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/InstalledRouter.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/InstalledRouter.java
@@ -0,0 +1,23 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package issues.i3729.api;
+
+import io.jooby.Context;
+import io.jooby.Jooby;
+
+public class InstalledRouter extends Jooby {
+
+  {
+    /*
+     * Installed operation.
+     *
+     * @operationId installedOp
+     */
+    get("/installed", Context::getRequestPath);
+
+    mount(new MountedRouter());
+  }
+}
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/MountedApp.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/MountedApp.java
@@ -0,0 +1,26 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package issues.i3729.api;
+
+import io.jooby.Context;
+import io.jooby.Jooby;
+
+public class MountedApp extends Jooby {
+  {
+    /*
+     * This is the main router.
+     */
+    get("/main", Context::getRequestPath);
+
+    mount(new MountedRouter());
+
+    mount("/mount-point", new MountedRouter());
+
+    install(InstalledRouter::new);
+
+    install("/install-point", InstalledRouter::new);
+  }
+}
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/MountedDocTest.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/MountedDocTest.java
@@ -0,0 +1,92 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package issues.i3729.api;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import io.jooby.openapi.OpenAPIResult;
+import io.jooby.openapi.OpenAPITest;
+
+public class MountedDocTest {
+
+  @OpenAPITest(value = MountedApp.class)
+  public void shouldGenerateDocFromMountedApp(OpenAPIResult result) {
+    assertEquals(
+        "openapi: 3.0.1\n"
+            + "info:\n"
+            + "  title: Mounted API\n"
+            + "  description: Mounted API description\n"
+            + "  version: \"1.0\"\n"
+            + "paths:\n"
+            + "  /main:\n"
+            + "    get:\n"
+            + "      summary: This is the main router.\n"
+            + "      operationId: getMain\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: Success\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                type: string\n"
+            + "  /mounted:\n"
+            + "    get:\n"
+            + "      summary: Mounted operation.\n"
+            + "      operationId: mountedOp3\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: Success\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                type: string\n"
+            + "  /mount-point/mounted:\n"
+            + "    get:\n"
+            + "      summary: Mounted operation.\n"
+            + "      operationId: mountedOp2\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: Success\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                type: string\n"
+            + "  /installed:\n"
+            + "    get:\n"
+            + "      summary: Installed operation.\n"
+            + "      operationId: installedOp\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: Success\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                type: string\n"
+            + "  /install-point/installed:\n"
+            + "    get:\n"
+            + "      summary: Installed operation.\n"
+            + "      operationId: installedOp2\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: Success\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                type: string\n"
+            + "  /install-point/mounted:\n"
+            + "    get:\n"
+            + "      summary: Mounted operation.\n"
+            + "      operationId: mountedOp4\n"
+            + "      responses:\n"
+            + "        \"200\":\n"
+            + "          description: Success\n"
+            + "          content:\n"
+            + "            application/json:\n"
+            + "              schema:\n"
+            + "                type: string\n",
+        result.toYaml());
+  }
+}
diff --git a/modules/jooby-openapi/src/test/java/issues/i3729/api/MountedRouter.java b/modules/jooby-openapi/src/test/java/issues/i3729/api/MountedRouter.java
@@ -0,0 +1,23 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package issues.i3729.api;
+
+import io.jooby.Context;
+import io.jooby.Jooby;
+
+public class MountedRouter extends Jooby {
+
+  {
+    get("/mounted", this::mountedOp);
+  }
+
+  /*
+   * Mounted operation.
+   */
+  private String mountedOp(Context context) {
+    return "";
+  }
+}
