open-api: disable javadoc parsing by default

- fix #3841
- update docs

Author: jknack

docs/asciidoc/modules/openapi.adoc

@@ -11,7 +11,7 @@ This library supports:
 - https://github.com/Redocly/redoc[Redoc] (Optional)
 - AsciiDoc Output (Optional)
 
-Checkout the [demo project](https://github.com/jooby-project/library-demo)
+Checkout the https://github.com/jooby-project/library-demo[demo project]
 
 === Configuration
 
@@ -34,10 +34,7 @@ Checkout the [demo project](https://github.com/jooby-project/library-demo)
           <goal>openapi</goal>
         </goals>
         <configuration>
-          <specVersion>...</specVersion>
-          <adoc>
-            <file>...</file>
-          </adoc>
+          ...
         </configuration>
       </execution>
     </executions>
@@ -66,6 +63,12 @@ plugins {
 mainClassName = "myapp.App"
 ...
 
+// Configuration
+
+openAPI {
+  ....
+}
+
 // Run openAPI task on joobyRun
 joobyRun.dependsOn openAPI
 
@@ -80,6 +83,49 @@ It may slow down `hot reload` process in case of large projects with a lot of co
 To avoid this behaviour you can specify maven build phase which suits your needs better (e.g. `prepare-package`).
 ====
 
+==== Options
+
+[cols="1,1,4a"]
+|===
+| Option | Default Value | Description
+
+|`adoc`
+| 
+|List of asciidoc files used as template to generate documentation:
+
+.Maven:
+
+    <adoc>
+      <file>guide.adoc</file>
+     </adoc>
+
+.Gradle:
+    {
+      adoc = ["guide.adoc"]
+    }
+
+|`basedir`
+| `${project.dir}`
+|Set base directory used it for loading openAPI template file name.
+
+|`includes`
+| 
+|Regular expression used to includes/keep route. Example: `/api/.*`.
+
+|`excludes`
+|
+|Regular expression used to excludes route. Example: `/web`.
+
+|`specVersion`
+|`3.0`
+|Set the desired spec output
+
+|`templateName`
+|`openapi.yaml`
+|Set openAPI template file name.
+
+|===
+
 === Usage
 
 To learn how it works, let's write a simple Pet API:
@@ -204,7 +250,7 @@ properties filter routes by their path pattern. The filter is a regular expressi
 
 === Documenting your API
 
-Full/complete example available [here](https://github.com/jooby-project/library-demo)
+Full/complete example available https://github.com/jooby-project/library-demo[here]
 
 ==== JavaDoc comments
 

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

@@ -30,6 +30,9 @@
 import io.jooby.Router;
 
 public class JavaDocParser {
+
+  public static final JavaDocParser NOOP = new JavaDocParser(List.of());
+
   private record ScriptRef(String operationId, DetailAST comment) {}
 
   private final List<Path> baseDir;
@@ -47,6 +50,19 @@ public Optional<ClassDoc> parse(String typeName) {
     return ofNullable(traverse(resolveType(typeName)).get(typeName));
   }
 
+  public DetailAST resolve(Path path) {
+    return lookup(path)
+        .map(
+            it ->
+                cache.computeIfAbsent(
+                    it,
+                    throwingFunction(
+                        filePath -> {
+                          return parseFile(filePath.toFile(), JavaParser.Options.WITH_COMMENTS);
+                        })))
+        .orElse(JavaDocNode.EMPTY_AST);
+  }
+
   private Map<String, ClassDoc> traverse(DetailAST tree) {
     var classes = new HashMap<String, ClassDoc>();
     traverse(
@@ -307,26 +323,13 @@ private String computePath(String prefix, String pattern) {
     return Router.noTrailingSlash(Router.normalizePath(prefix + pattern));
   }
 
-  public DetailAST resolve(Path path) {
-    return lookup(path)
-        .map(
-            it ->
-                cache.computeIfAbsent(
-                    it,
-                    throwingFunction(
-                        filePath -> {
-                          return parseFile(filePath.toFile(), JavaParser.Options.WITH_COMMENTS);
-                        })))
-        .orElse(JavaDocNode.EMPTY_AST);
-  }
-
   private DetailAST resolveType(String typeName) {
     var segments = typeName.split("\\.");
     segments[segments.length - 1] = segments[segments.length - 1] + ".java";
     return resolve(Paths.get(String.join(File.separator, segments)));
   }
 
-  protected Optional<Path> lookup(Path path) {
+  private Optional<Path> lookup(Path path) {
     return baseDir.stream()
         .map(parentDir -> parentDir.resolve(path))
         .filter(Files::exists)

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

@@ -164,7 +164,7 @@ public List<Path> write(
 
   private SpecVersion specVersion = SpecVersion.V30;
 
-  private AsciiDocContext asciidoc;
+  private boolean javadoc = true;
 
   /** Default constructor. */
   public OpenAPIGenerator() {}
@@ -216,17 +216,15 @@ public OpenAPIGenerator() {}
    * @return Model.
    */
   public @NonNull OpenAPI generate(@NonNull String classname) {
-    ClassLoader classLoader =
-        Optional.ofNullable(this.classLoader).orElseGet(getClass()::getClassLoader);
+    var classLoader = Optional.ofNullable(this.classLoader).orElseGet(getClass()::getClassLoader);
 
-    ClassSource source = new ClassSource(classLoader);
+    var source = new ClassSource(classLoader);
 
     /* Create OpenAPI from template and make sure min required information is present: */
-    OpenAPIExt openapi =
-        new OpenApiTemplate(specVersion).fromTemplate(basedir, classLoader, templateName);
+    var openapi = new OpenApiTemplate(specVersion).fromTemplate(basedir, classLoader, templateName);
 
     var mainType = TypeFactory.fromJavaName(classname);
-    var javadoc = new JavaDocParser(sources);
+    var javadoc = this.javadoc ? new JavaDocParser(sources) : JavaDocParser.NOOP;
 
     if (openapi.getInfo() == null) {
       var info = new Info();
@@ -249,14 +247,13 @@ public OpenAPIGenerator() {}
               });
     }
 
-    RouteParser routes = new RouteParser();
+    var routes = new RouteParser();
     var json = jsonMapper();
     var yaml = yamlMapper();
-    ParserContext ctx =
-        new ParserContext(specVersion, json, yaml, source, mainType, javadoc, debug);
-    List<OperationExt> operations = routes.parse(ctx, openapi);
+    var ctx = new ParserContext(specVersion, json, yaml, source, mainType, javadoc, debug);
+    var operations = routes.parse(ctx, openapi);
 
-    String contextPath = ContextPathParser.parse(ctx);
+    var contextPath = ContextPathParser.parse(ctx);
 
     openapi.setSource(Optional.ofNullable(ctx.getMainClass()).orElse(classname));
 
@@ -268,20 +265,20 @@ public OpenAPIGenerator() {}
     ctx.schemas().forEach(schema -> openapi.schema(schema.getName(), schema));
 
     Map<String, Tag> globalTags = new LinkedHashMap<>();
-    Paths paths = new Paths();
-    for (OperationExt operation : operations) {
-      String pattern = operation.getPath();
+    var paths = new Paths();
+    for (var operation : operations) {
+      var pattern = operation.getPath();
       if (!includes(pattern) || excludes(pattern)) {
         log.debug("skipping {}", pattern);
         continue;
       }
-      Map<String, String> regexMap = new HashMap<>();
+      var regexMap = new HashMap<String, String>();
       Router.pathKeys(
           pattern, (key, value) -> Optional.ofNullable(value).ifPresent(v -> regexMap.put(key, v)));
       if (!regexMap.isEmpty()) {
-        for (Map.Entry<String, String> e : regexMap.entrySet()) {
-          String name = e.getKey();
-          String regex = e.getValue();
+        for (var e : regexMap.entrySet()) {
+          var name = e.getKey();
+          var regex = e.getValue();
           operation
               .getParameter(name)
               .ifPresent(parameter -> parameter.getSchema().setPattern(regex));
@@ -296,7 +293,7 @@ public OpenAPIGenerator() {}
           }
         }
       }
-      PathItem pathItem = paths.computeIfAbsent(pattern, k -> new PathItem());
+      var pathItem = paths.computeIfAbsent(pattern, k -> new PathItem());
       pathItem.operation(PathItem.HttpMethod.valueOf(operation.getMethod()), operation);
       Optional.ofNullable(operation.getPathSummary()).ifPresent(pathItem::setSummary);
       Optional.ofNullable(operation.getPathDescription()).ifPresent(pathItem::setDescription);
@@ -345,12 +342,12 @@ private Optional<Boolean> pattern(String pattern, String value) {
   }
 
   private void defaults(String classname, String contextPath, OpenAPIExt openapi) {
-    Info info = openapi.getInfo();
+    var info = openapi.getInfo();
     if (info == null) {
       info = new Info();
       openapi.info(info);
     }
-    String appname = appname(classname);
+    var appname = appname(classname);
     info.setTitle(Optional.ofNullable(info.getTitle()).orElse(appname + " API"));
     info.setDescription(
         Optional.ofNullable(info.getDescription()).orElse(appname + " API description"));
@@ -561,7 +558,25 @@ public void setSpecVersion(String version) {
     }
   }
 
-  protected AsciiDocContext createAsciidoc(Path basedir, OpenAPIExt openapi) {
+  /**
+   * True/On to enabled.
+   *
+   * @param javadoc True/On to enabled.
+   */
+  public void setJavadoc(String javadoc) {
+    this.javadoc = Boolean.parseBoolean(javadoc) || "on".equalsIgnoreCase(javadoc);
+  }
+
+  /**
+   * True/On to enabled.
+   *
+   * @return True/On to enabled.
+   */
+  public boolean getJavadoc() {
+    return javadoc;
+  }
+
+  private AsciiDocContext createAsciidoc(Path basedir, OpenAPIExt openapi) {
     return new AsciiDocContext(basedir, jsonMapper(), yamlMapper(), openapi);
   }
 

modules/jooby-openapi/src/test/java/io/jooby/openapi/OpenAPIExtension.java

@@ -45,6 +45,7 @@ public Object resolveParameter(ParameterContext parameterContext, ExtensionConte
             : EnumSet.copyOf(Arrays.asList(metadata.debug()));
 
     OpenAPIGenerator tool = newTool(debugOptions);
+    tool.setJavadoc(metadata.javadoc());
     tool.setSpecVersion(metadata.version().name());
     String templateName = metadata.templateName();
     if (templateName.isEmpty()) {

modules/jooby-openapi/src/test/java/io/jooby/openapi/OpenAPITest.java

@@ -34,4 +34,6 @@
   String templateName() default "";
 
   SpecVersion version() default SpecVersion.V30;
+
+  String javadoc() default "ON";
 }

modules/jooby-openapi/src/test/java/issues/i3841/App3841.java

@@ -0,0 +1,17 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package issues.i3841;
+
+import static io.jooby.openapi.MvcExtensionGenerator.toMvcExtension;
+
+import io.jooby.Jooby;
+
+/** App with or without doc. Description doc. */
+public class App3841 extends Jooby {
+  {
+    mvc(toMvcExtension(C3841.class));
+  }
+}

modules/jooby-openapi/src/test/java/issues/i3841/C3841.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.i3841;
+
+import io.jooby.annotation.GET;
+import io.jooby.annotation.Path;
+import io.jooby.annotation.QueryParam;
+
+/** Paths. */
+@Path("/3841")
+public class C3841 {
+
+  /**
+   * Hello endpoint.
+   *
+   * @param name Name arg.
+   * @return Hello endpoint.
+   */
+  @GET
+  public String hello(@QueryParam String name) {
+    return null;
+  }
+}