- integrate ascii doc into openapi generator: maven/gradle plugin

- fix schema data iteration to support schema $ref
- make schema filter pretty print output

Author: jknack

docs/src/main/java/io/jooby/adoc/DocGenerator.java

@@ -87,29 +87,29 @@ public static void generate(Path basedir, boolean publish, boolean v1, boolean d
       pb.step();
 
       if (doAscii) {
-        Asciidoctor asciidoctor = Asciidoctor.Factory.create();
-
-        asciidoctor.convertFile(
-            asciidoc.resolve("index.adoc").toFile(),
-            createOptions(asciidoc, outdir, version, null, asciidoc.resolve("index.adoc")));
-        var index = outdir.resolve("index.html");
-        Files.writeString(index, hljs(Files.readString(index)));
-        pb.step();
-
-        Stream.of(treeDirs)
-            .forEach(
-                throwingConsumer(
-                    name -> {
-                      Path modules = outdir.resolve(name);
-                      Files.createDirectories(modules);
-                      Files.walk(asciidoc.resolve(name))
-                          .filter(Files::isRegularFile)
-                          .forEach(
-                              module -> {
-                                processModule(asciidoctor, asciidoc, module, outdir, name, version);
-                                pb.step();
-                              });
-                    }));
+        try (var asciidoctor = Asciidoctor.Factory.create()) {
+          asciidoctor.convertFile(
+              asciidoc.resolve("index.adoc").toFile(),
+              createOptions(asciidoc, outdir, version, null, asciidoc.resolve("index.adoc")));
+          var index = outdir.resolve("index.html");
+          Files.writeString(index, hljs(Files.readString(index)));
+          pb.step();
+
+          Stream.of(treeDirs)
+              .forEach(
+                  throwingConsumer(
+                      name -> {
+                        Path modules = outdir.resolve(name);
+                        Files.createDirectories(modules);
+                        Files.walk(asciidoc.resolve(name))
+                            .filter(Files::isRegularFile)
+                            .forEach(
+                                module -> {
+                                  processModule(asciidoctor, asciidoc, module, outdir, name, version);
+                                  pb.step();
+                                });
+                      }));
+        }
       }
 
       // LICENSE
@@ -242,6 +242,7 @@ private static Options createOptions(Path basedir, Path outdir, String version,
     var attributes = Attributes.builder();
 
     attributes.attribute("docfile", docfile.toString());
+    attributes.attribute("stylesheet", "js/styles/site.css");
     attributes.attribute("love", "♡");
     attributes.attribute("docinfo", "shared");
     attributes.title(title == null ? "jooby: do more! more easily!!" : "jooby: " + title);
@@ -280,7 +281,7 @@ private static Options createOptions(Path basedir, Path outdir, String version,
     attributes.attribute("date", DateTimeFormatter.ISO_INSTANT.format(Instant.now()));
 
     OptionsBuilder options = Options.builder();
-    options.backend("html");
+    options.backend("html5");
 
     options.attributes(attributes.build());
     options.baseDir(basedir.toAbsolutePath().toFile());

modules/jooby-gradle-plugin/src/main/java/io/jooby/gradle/OpenAPITask.java

@@ -17,8 +17,11 @@
 import java.io.File;
 import java.nio.file.Path;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
+import static java.util.Optional.ofNullable;
+
 /**
  * Generate an OpenAPI file from a jooby application.
  *
@@ -37,6 +40,8 @@ public class OpenAPITask extends BaseTask {
 
   private String specVersion;
 
+  private List<File> adoc;
+
   /**
    * Creates an OpenAPI task.
    */
@@ -61,7 +66,8 @@ public void generate() throws Throwable {
               .map(File::toPath);
         })
         .distinct()
-        .toList();    Path outputDir = classes(getProject(), false);
+        .toList();
+    Path outputDir = classes(getProject(), false);
 
     ClassLoader classLoader = createClassLoader(projects);
 
@@ -82,9 +88,10 @@ public void generate() throws Throwable {
 
     OpenAPI result = tool.generate(mainClass);
 
-    for (OpenAPIGenerator.Format format : OpenAPIGenerator.Format.values()) {
-      Path output = tool.export(result, format);
-      getLogger().info("  writing: " + output);
+    var adocPath = ofNullable(adoc).orElse(List.of()).stream().map(File::toPath).toList();
+    for (var format : OpenAPIGenerator.Format.values()) {
+      tool.export(result, format, Map.of("adoc", adocPath))
+          .forEach(output -> getLogger().info("  writing: " + output));
     }
   }
 
@@ -188,6 +195,26 @@ public void setSpecVersion(String specVersion) {
     this.specVersion = specVersion;
   }
 
+  /**
+   * Optionally generates adoc output.
+   *
+   * @return List of adoc templates.
+   */
+  @Input
+  @org.gradle.api.tasks.Optional
+  public List<File> getAdoc() {
+    return adoc;
+  }
+
+  /**
+   * Set adoc templates to build.
+   *
+   * @param adoc Adoc templates to build.
+   */
+  public void setAdoc(List<File> adoc) {
+    this.adoc = adoc;
+  }
+
   private Optional<String> trim(String value) {
     if (value == null || value.trim().isEmpty()) {
       return Optional.empty();

modules/jooby-maven-plugin/src/main/java/io/jooby/maven/OpenAPIMojo.java

@@ -5,12 +5,15 @@
  */
 package io.jooby.maven;
 
+import static java.util.Optional.ofNullable;
 import static org.apache.maven.plugins.annotations.LifecyclePhase.PROCESS_CLASSES;
 import static org.apache.maven.plugins.annotations.ResolutionScope.COMPILE_PLUS_RUNTIME;
 
+import java.io.File;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
 import org.apache.maven.plugins.annotations.Mojo;
@@ -20,7 +23,6 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 import io.jooby.openapi.OpenAPIGenerator;
-import io.swagger.v3.oas.models.OpenAPI;
 
 /**
  * Generate an OpenAPI file from a jooby application.
@@ -47,6 +49,8 @@ public class OpenAPIMojo extends BaseMojo {
   @Parameter(property = "openAPI.specVersion")
   private String specVersion;
 
+  @Parameter private List<File> adoc;
+
   @Override
   protected void doExecute(@NonNull List<MavenProject> projects, @NonNull String mainClass)
       throws Exception {
@@ -73,16 +77,17 @@ protected void doExecute(@NonNull List<MavenProject> projects, @NonNull String m
     trim(includes).ifPresent(tool::setIncludes);
     trim(excludes).ifPresent(tool::setExcludes);
 
-    OpenAPI result = tool.generate(mainClass);
+    var result = tool.generate(mainClass);
 
-    for (OpenAPIGenerator.Format format : OpenAPIGenerator.Format.values()) {
-      Path output = tool.export(result, format);
-      getLog().info("  writing: " + output);
+    var adocPath = ofNullable(adoc).orElse(List.of()).stream().map(File::toPath).toList();
+    for (var format : OpenAPIGenerator.Format.values()) {
+      tool.export(result, format, Map.of("adoc", adocPath))
+          .forEach(output -> getLog().info("  writing: " + output));
     }
   }
 
   private Optional<String> trim(String value) {
-    if (value == null || value.trim().length() == 0) {
+    if (value == null || value.trim().isEmpty()) {
       return Optional.empty();
     }
     return Optional.of(value.trim());
@@ -131,4 +136,12 @@ public String getSpecVersion() {
   public void setSpecVersion(String specVersion) {
     this.specVersion = specVersion;
   }
+
+  public List<File> getAdoc() {
+    return adoc;
+  }
+
+  public void setAdoc(List<File> adoc) {
+    this.adoc = adoc;
+  }
 }

modules/jooby-maven-plugin/src/main/java/io/jooby/maven/RunMojo.java

@@ -24,6 +24,8 @@
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
 import org.apache.maven.project.MavenProject;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import io.jooby.run.JoobyRun;
 import io.jooby.run.JoobyRunOptions;
@@ -42,8 +44,10 @@
 @Execute(phase = PROCESS_CLASSES)
 public class RunMojo extends BaseMojo {
 
+  private static final Logger log = LoggerFactory.getLogger(RunMojo.class);
+
   static {
-    /** Turn off shutdown hook on Server. */
+    /* Turn off shutdown hook on Server. */
     System.setProperty("jooby.useShutdownHook", "false");
   }
 
@@ -97,7 +101,13 @@ protected void doExecute(List<MavenProject> projects, String mainClass) throws T
                   var error = result.hasExceptions();
                   // Success?
                   if (error) {
-                    getLog().debug("Compilation error found: " + path);
+                    var filename = path.getFileName().toFile().toString();
+                    var isSource = filename.endsWith(".java") || filename.endsWith(".kt");
+                    for (Throwable exception : result.getExceptions()) {
+                      if (!isSource) {
+                        getLog().error(exception);
+                      }
+                    }
                   }
                   return !error;
                 });
@@ -213,8 +223,7 @@ protected void setUseTestScope(boolean useTestScope) {
    * @return Request.
    */
   private MavenExecutionRequest mavenRequest(String goal) {
-    return DefaultMavenExecutionRequest.copy(session.getRequest())
-        .setGoals(Collections.singletonList(goal));
+    return DefaultMavenExecutionRequest.copy(session.getRequest()).setGoals(List.of(goal));
   }
 
   private Set<Path> sourceDirectories(MavenProject project, boolean useTestScope) {

modules/jooby-openapi/pom.xml

@@ -56,7 +56,11 @@
       <artifactId>asciidoctorj</artifactId>
       <version>3.0.1</version>
     </dependency>
-
+    <dependency>
+      <groupId>org.asciidoctor</groupId>
+      <artifactId>asciidoctorj-pdf</artifactId>
+      <version>2.3.23</version>
+    </dependency>
     <dependency>
       <groupId>io.pebbletemplates</groupId>
       <artifactId>pebble</artifactId>
@@ -78,6 +82,12 @@
       <artifactId>guava</artifactId>
     </dependency>
 
+    <dependency>
+      <groupId>jakarta.data</groupId>
+      <artifactId>jakarta.data-api</artifactId>
+      <version>1.0.1</version>
+    </dependency>
+
     <!-- Test dependencies -->
     <dependency>
       <groupId>org.junit.jupiter</groupId>

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/AsciiDocGenerator.java

@@ -13,6 +13,10 @@
 import java.util.Map;
 import java.util.Optional;
 
+import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.Options;
+import org.asciidoctor.SafeMode;
+
 import io.jooby.internal.openapi.asciidoc.Filters;
 import io.jooby.internal.openapi.asciidoc.Functions;
 import io.jooby.internal.openapi.asciidoc.SnippetResolver;
@@ -41,6 +45,23 @@ public static String generate(OpenAPIExt openAPI, Path index) throws IOException
     return writer.toString().trim();
   }
 
+  public static void export(Path baseDir, Path input, Path outputDir) {
+    try (var asciidoctor = Asciidoctor.Factory.create()) {
+
+      var options =
+          Options.builder()
+              .backend("html5")
+              .baseDir(baseDir.toFile())
+              .toDir(outputDir.toFile())
+              .mkDirs(true)
+              .safe(SafeMode.UNSAFE)
+              .build();
+
+      // Perform the conversion
+      asciidoctor.convertFile(input.toFile(), options);
+    }
+  }
+
   @SuppressWarnings("unchecked")
   private static PebbleEngine newEngine(OpenAPIExt openapi, Path baseDir) {
     var json = (openapi.getSpecVersion() == SpecVersion.V30 ? Json.mapper() : Json31.mapper());

modules/jooby-openapi/src/main/java/io/jooby/internal/openapi/MixinHook.java

@@ -0,0 +1,75 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal.openapi;
+
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.swagger.annotations.ApiModelProperty;
+import jakarta.data.page.Page;
+import jakarta.data.page.PageRequest;
+
+public class MixinHook {
+
+  @JsonPropertyOrder({
+    "content",
+    "numberOfElements",
+    "totalElements",
+    "totalPages",
+    "pageRequest",
+    "nextPageRequest",
+    "previousPageRequest"
+  })
+  public abstract static class PageMixin<T> implements Page<T> {
+    @JsonProperty("content")
+    @Override
+    public abstract List<T> content();
+
+    @JsonProperty("numberOfElements")
+    @Override
+    public abstract int numberOfElements();
+
+    @Override
+    @JsonProperty("pageRequest")
+    public abstract PageRequest pageRequest();
+
+    @Override
+    @JsonProperty("nextPageRequest")
+    public abstract PageRequest nextPageRequest();
+
+    @Override
+    @JsonProperty("previousPageRequest")
+    public abstract PageRequest previousPageRequest();
+
+    @Override
+    @JsonProperty("totalElements")
+    public abstract long totalElements();
+
+    @Override
+    @JsonProperty("totalPages")
+    public abstract long totalPages();
+  }
+
+  @JsonPropertyOrder({"page", "size"})
+  public abstract static class PageRequestMixin implements PageRequest {
+    @JsonProperty("page")
+    @Override
+    @ApiModelProperty("The page to be returned")
+    public abstract long page();
+
+    @JsonProperty("size")
+    @Override
+    @ApiModelProperty("The requested size of each page")
+    public abstract int size();
+  }
+
+  public static void mixin(ObjectMapper mapper) {
+    mapper.addMixIn(jakarta.data.page.Page.class, PageMixin.class);
+    mapper.addMixIn(jakarta.data.page.PageRequest.class, PageRequestMixin.class);
+  }
+}