Improve OpenAPI experience

Author: Yaytay

query-engine/docs/Parameters/uk.co.spudsoft.query.main.Parameters.adoc

@@ -207,4 +207,10 @@ Note that the default value for the outputCacheDir is probably a bad choice for
 | [[enableBearerAuth]]enableBearerAuth
 | boolean
 | If set to false any basic auth header will be ignored.
+| [[openApiExplorerUrl]]openApiExplorerUrl
+| link:https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/String.html[String]
+| Get the URL to the minified OpenAPI Explorer JS that is to be used for displaying The API documentation.The default value is (something like) "https://unpkg.com/openapi-explorer@2.2.733/dist/browser/openapi-explorer.min.js".
+ 
+
+It is not usually necessary to set this.
 |===

query-engine/docs/query-engine-compose.yml

@@ -50,7 +50,7 @@ services:
     - 16686:16686
 
   query-engine:
-    image: ghcr.io/yaytay/query-engine-design-mode:0.0.46
+    image: ghcr.io/yaytay/query-engine-design-mode:0.0.46-5-main
     ports:
     - 2000:8080
     volumes:

query-engine/pom.xml

@@ -99,7 +99,7 @@
     <dependency>
       <groupId>uk.co.spudsoft</groupId>
       <artifactId>vertx-resteasy-helpers</artifactId>
-      <version>0.0.25</version>
+      <version>0.0.27</version>
       <exclusions>
         <exclusion>
           <groupId>jakarta.activation</groupId>

query-engine/src/main/java/uk/co/spudsoft/query/main/Main.java

@@ -514,7 +514,7 @@ protected Future<Integer> innerMain(String[] args, PrintStream stdout) {
     );
 
     OpenAPIConfiguration openApiConfig = createOpenapiConfiguration(controllers);
-    OpenApiHandler openApiHandler = new OpenApiHandler(this, openApiConfig, "/api");
+    OpenApiHandler openApiHandler = new OpenApiHandler(this, openApiConfig, "/api", params.getOpenApiExplorerUrl());
     ModelConverters.getInstance(true).addConverter(new OpenApiModelConverter());
 
     PipelineExecutor pipelineExecutor = new PipelineExecutorImpl(filterFactory, params.getSecrets());

query-engine/src/main/java/uk/co/spudsoft/query/main/Parameters.java

@@ -246,6 +246,15 @@ public class Parameters {
    */
   private String managementEndpointUrl;
 
+  /**
+   * The URL to the minified OpenAPI Explorer JS that is to be used for displaying The API documentation.
+   * <p>
+   * The default value is (something like) "https://unpkg.com/openapi-explorer@2.2.733/dist/browser/openapi-explorer.min.js".
+   * <p>
+   * It is not usually necessary to set this.
+   */
+  private String openApiExplorerUrl;
+  
   /**
    * Configuration of the session management for the UI and REST API.
    */
@@ -929,6 +938,29 @@ public void setEnableBearerAuth(boolean enableBearerAuth) {
     this.enableBearerAuth = enableBearerAuth;
   }
 
+  /**
+   * Get the URL to the minified OpenAPI Explorer JS that is to be used for displaying The API documentation.
+   * The default value is (something like) "https://unpkg.com/openapi-explorer@2.2.733/dist/browser/openapi-explorer.min.js".
+   * <p>
+   * It is not usually necessary to set this.
+   * @return the URL to the minified OpenAPI Explorer JS that is to be used for displaying The API documentation.
+   */
+  public String getOpenApiExplorerUrl() {
+    return openApiExplorerUrl;
+  }
+
+  /**
+   * Get the URL to the minified OpenAPI Explorer JS that is to be used for displaying The API documentation.
+   * The default value is (something like) "https://unpkg.com/openapi-explorer@2.2.733/dist/browser/openapi-explorer.min.js".
+   * <p>
+   * It is not usually necessary to set this.
+   * 
+   * @param openApiExplorerUrl the URL to the minified OpenAPI Explorer JS that is to be used for displaying The API documentation.
+   */
+  public void setOpenApiExplorerUrl(String openApiExplorerUrl) {
+    this.openApiExplorerUrl = openApiExplorerUrl;
+  }
+
   /**
    * Validate the provided parameters.
    * 

query-engine/src/main/java/uk/co/spudsoft/query/main/Version.java

@@ -34,7 +34,7 @@ public final class Version {
   /**
    * The project version, as set in the Maven pom.xml.
    */
-  public static final String MAVEN_PROJECT_VERSION = "0.0.45-12-main";
+  public static final String MAVEN_PROJECT_VERSION = "0.0.46-5-main";
 
   private Version() {
   }

query-engine/src/main/java/uk/co/spudsoft/query/pipeline/PipelineNodesTree.java

@@ -49,10 +49,13 @@ private PipelineNodesTree() {
     @JsonSubTypes.Type(value = PipelineFile.class)
   })
   @Schema(description = """
-                        <P>
                         Base class for pipelines and the directories that contain them.
-                        </P>
-                        """)
+                        """
+          , oneOf = {
+                  PipelineDir.class
+                  , PipelineFile.class
+          }
+  )
   public static class PipelineNode extends AbstractNode<PipelineNode> {
 
     /**
@@ -103,11 +106,9 @@ public String getPath() {
      */
     @Override
     @Schema(description = """
-                          <P>
                           The children of the node.
-                          </P>
                           <P>
-                          If this is null then the node is a file, otherwise it is a directory.
+                          If this is null then the node is a PipelineFile, otherwise it is a PipelineDir.
                           </P>
                           """)
     public List<PipelineNode> getChildren() {
@@ -195,9 +196,7 @@ public PipelineDir(String path, List<PipelineNode> children) {
     @Schema(nullable = false
             , requiredMode = Schema.RequiredMode.REQUIRED
             , description = """
-                          <P>
                           The children of the directory.
-                          </P>
                           """)
     public List<PipelineNode> getChildren() {
       return super.getChildren(); // Generated from nbfs://nbhost/SystemFileSystem/Templates/Classes/Code/OverriddenMethodBody

query-engine/src/main/java/uk/co/spudsoft/query/web/rest/DocHandler.java

@@ -185,12 +185,16 @@ public void getAvailable(
   @Operation(description = "Return some documentation")
   @ApiResponse(
           responseCode = "200"
-          , description = "A documnent about Query Engine."
+          , description = "A document about Query Engine."
           , content = @Content(mediaType = "text/markdown")
   )
   public void getDoc(
           @Suspended final AsyncResponse response
-          , @PathParam("path") String path
+          , @Schema(
+                  description = "The path to the document, as returned by a call to get /api/docs"
+            )
+            @PathParam("path") 
+            String path
   ) {
 
     try {

query-engine/src/main/java/uk/co/spudsoft/query/web/rest/DocNodesTree.java

@@ -48,7 +48,12 @@ private DocNodesTree() {
                         <P>
                         Base class for documentation files and the directories that contain them.
                         </P>
-                        """)
+                        """
+          , oneOf = {
+                  DocDir.class
+                  , DocFile.class
+          }
+  )
   public static class DocNode extends AbstractNode<DocNode> {
 
     private final String path; 

query-engine/src/main/java/uk/co/spudsoft/query/web/rest/FormIoHandler.java

@@ -137,8 +137,20 @@ public FormIoHandler(PipelineDefnLoader loader, FilterFactory filterFactory, boo
   )
   public void getFormIO(
           @Suspended final AsyncResponse response
-          , @PathParam("path") String path
-          , @QueryParam("columns") Integer columns
+          , @Schema(
+                  description = "The path to the quiery, as returned by a call to get /api/info/available"
+            )
+            @PathParam("path")
+            String path
+          , @Schema(
+                  description = "The number of columns to use when displaying arguments"
+                  , minimum = "1"
+                  , maximum = "12"
+                  , defaultValue = "1"
+                  , requiredMode = Schema.RequiredMode.NOT_REQUIRED
+            )
+            @QueryParam("columns") 
+            Integer columns
   ) {
 
     if (columns != null)  {