Merge pull request #58 from sanctuuary/open-api

Improve the OpenAPI documentation

pom.xml

@@ -71,6 +71,13 @@
 			<version>3.2.2</version>
 		</dependency>
 
+		<!-- https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-validation -->
+		<dependency>
+			<groupId>org.springframework.boot</groupId>
+			<artifactId>spring-boot-starter-validation</artifactId>
+			<version>3.2.2</version>
+		</dependency>
+
 		<!-- https://mvnrepository.com/artifact/com.h2database/h2 -->
 		<dependency>
 			<groupId>com.h2database</groupId>

src/main/java/nl/esciencecenter/restape/APEWorkflowMetadata.java

@@ -0,0 +1,88 @@
+package nl.esciencecenter.restape;
+
+import org.json.JSONObject;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import nl.uu.cs.ape.solver.solutionStructure.SolutionWorkflow;
+
+/**
+ * The {@link APEWorkflowMetadata} class represents metadata for a workflow solution from the APE solver.
+ * This class encapsulates the details and metadata of a workflow solution,
+ * including descriptive names, descriptions, the length of the solution, and benchmark information.
+ * It provides functionality to convert these details into a JSONObject for serialization or further processing.
+ */
+@Getter
+@NoArgsConstructor
+public class APEWorkflowMetadata {
+
+    private String workflowName;
+    private String descriptiveName;
+    private String description;
+    private int workflowLength;
+    private String runId;
+    private String cwlName;
+    private String figureName;
+    private String benchmarkFile; // Optional, indicates if benchmark data should be included.
+
+    /**
+     * Constructs a APEWorkflowMetadata instance from a given SolutionWorkflow and run configuration.
+     * 
+     * @param sol The SolutionWorkflow containing necessary details of the workflow solution.
+     * @param runID The identifier for the run to which this solution belongs.
+     * @param benchmark Indicates whether benchmark data is to be included for this solution.
+     */
+    public APEWorkflowMetadata(SolutionWorkflow sol, String runID, boolean benchmark) {
+        this.workflowName = sol.getFileName();
+        this.descriptiveName = sol.getDescriptiveName();
+        this.description = sol.getDescription();
+        this.workflowLength = sol.getSolutionLength();
+        this.runId = runID;
+        this.cwlName = sol.getFileName() + ".cwl";
+        this.figureName = sol.getFileName();
+        if (benchmark) {
+            this.benchmarkFile = sol.getFileName() + ".json";
+        }
+    }
+
+    /**
+     * Converts the APEWorkflowMetadata instance into a JSONObject representing its properties.
+     * This facilitates the serialization of the workflow solution's metadata to a JSON format,
+     * making it compatible with JSON-based data handling, APIs, and storage mechanisms.
+     * 
+     * @return A JSONObject representation of the APEWorkflowMetadata instance.
+     */
+    public JSONObject toJSONObject() {
+        JSONObject json = new JSONObject();
+        json.put("workflow_name", this.workflowName);
+        json.put("descriptive_name", this.descriptiveName);
+        json.put("description", this.description);
+        json.put("workflow_length", this.workflowLength);
+        json.put("run_id", this.runId);
+        json.put("cwl_name", this.cwlName);
+        json.put("figure_name", this.figureName);
+        if (this.benchmarkFile != null) {
+            json.put("benchmark_file", this.benchmarkFile);
+        }
+        return json;
+    }
+
+    /**
+     * Converts the APEWorkflowMetadata instance into a JSON string representing its properties.
+     * 
+     * @return A JSON string representation of the APEWorkflowMetadata instance.
+     */
+    public String toString() {
+        JSONObject json = new JSONObject();
+        json.put("workflow_name", this.workflowName);
+        json.put("descriptive_name", this.descriptiveName);
+        json.put("description", this.description);
+        json.put("workflow_length", this.workflowLength);
+        json.put("run_id", this.runId);
+        json.put("cwl_name", this.cwlName);
+        json.put("figure_name", this.figureName);
+        if (this.benchmarkFile != null && !this.benchmarkFile.isEmpty()) {
+            json.put("benchmark_file", this.benchmarkFile);
+        }
+        return json.toString();
+    }
+}

src/main/java/nl/esciencecenter/restape/ApeAPI.java

@@ -1,7 +1,10 @@
 package nl.esciencecenter.restape;
 
 import java.io.IOException;
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.List;
+
 import nl.uu.cs.ape.APE;
 import nl.uu.cs.ape.configuration.APECoreConfig;
 import nl.uu.cs.ape.configuration.APERunConfig;
@@ -10,7 +13,6 @@
 import nl.uu.cs.ape.models.AllPredicates;
 import nl.uu.cs.ape.models.AllTypes;
 import nl.uu.cs.ape.models.logic.constructs.TaxonomyPredicate;
-import nl.uu.cs.ape.solver.solutionStructure.SolutionWorkflow;
 import nl.uu.cs.ape.solver.solutionStructure.SolutionsList;
 import nl.uu.cs.ape.utils.APEUtils;
 
@@ -139,13 +141,13 @@ public static JSONArray getConstraints(String configFileURL) throws OWLOntologyC
      * @param configJson - configuration of the synthesis run
      * @param benchmark  - boolean to indicate if the workflows should be
      *                   benchmarked
-     * @return - JSONArray with the metadata results of the synthesis, each element
+     * @return - List of {@link APEWorkflowMetadata}s with the metadata results of the synthesis, each element
      *         describes a workflow solution (name, length, runID, path to a CWL
      *         file, etc.).
      * @throws OWLOntologyCreationException
      * @throws IOException
      */
-    public static JSONArray runSynthesis(JSONObject configJson, boolean benchmark)
+    public static List<APEWorkflowMetadata> runSynthesis(JSONObject configJson, boolean benchmark)
             throws OWLOntologyCreationException, IOException {
 
         // Define the synthesis run ID
@@ -205,32 +207,22 @@ private static SolutionsList executeSynthesis(JSONObject configJson, String runI
      *                           of the synthesis as well as information about the
      *                           synthesis run.
      * @runID - ID of the synthesis run
-     * @return - JSONArray with the results of the synthesis, each element describes
+     * @return - List of {@link APEWorkflowMetadata}s with the results of the synthesis, each element describes
      *         a workflow solution (name, length, runID, path to a CWL file, etc.).
      */
-    private static JSONArray workflowMetadataToJson(SolutionsList candidateSolutions, String runID, boolean benchmark) {
-        JSONArray generatedSolutionsJson = new JSONArray();
+    private static List<APEWorkflowMetadata> workflowMetadataToJson(SolutionsList candidateSolutions, String runID, boolean benchmark) {
+        List<APEWorkflowMetadata> generatedSolutionsJson = new ArrayList<>();
 
         if (candidateSolutions.isEmpty()) {
-            return new JSONArray();
+            return new ArrayList<>();
         } else {
             // Generate objects that return the solutions in JSON format
             int noSolutions = candidateSolutions.getNumberOfSolutions();
             for (int i = 0; i < noSolutions; i++) {
-                SolutionWorkflow sol = candidateSolutions.get(i);
-                JSONObject solutionJson = new JSONObject();
-                solutionJson.put("workflow_name", sol.getFileName());
-                solutionJson.put("descriptive_name", sol.getDescriptiveName());
-                solutionJson.put("description", sol.getDescription());
-                solutionJson.put("workflow_length", sol.getSolutionLength());
-                solutionJson.put("run_id", runID);
-                // Add reference to the generated cwl file and figure
-                solutionJson.put("cwl_name", sol.getFileName() + ".cwl");
-                solutionJson.put("figure_name", sol.getFileName());
-                if (benchmark) {
-                    solutionJson.put("benchmark_file", sol.getFileName() + ".json");
-                }
-                generatedSolutionsJson.put(solutionJson);
+
+                APEWorkflowMetadata solutionJson = new APEWorkflowMetadata(candidateSolutions.get(i), runID, benchmark);
+
+                generatedSolutionsJson.add(solutionJson);
             }
             return generatedSolutionsJson;
         }

src/test/java/nl/esciencecenter/controller/RestApeControllerTest.java

@@ -5,10 +5,9 @@
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import java.nio.charset.StandardCharsets;
-import java.util.HashMap;
+import java.util.List;
 
 import org.apache.commons.io.FileUtils;
-import org.json.JSONArray;
 import org.json.JSONObject;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -18,7 +17,7 @@
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
 
-import nl.esciencecenter.controller.dto.CWLZip;
+import nl.esciencecenter.restape.APEWorkflowMetadata;
 import nl.esciencecenter.restape.ApeAPI;
 import nl.uu.cs.ape.utils.APEFiles;
 
@@ -140,10 +139,10 @@ void testPostZipCWLs() throws Exception {
                             StandardCharsets.UTF_8);
             JSONObject jsonObject = new JSONObject(content);
             jsonObject.put("solutions", "1");
-            JSONArray result = ApeAPI.runSynthesis(jsonObject, false);
+            List<APEWorkflowMetadata> result = ApeAPI.runSynthesis(jsonObject, false);
             assertFalse(result.isEmpty(), "The encoding should be SAT.");
-            String runID = result.getJSONObject(0).getString("run_id");
-            String cwlFile = result.getJSONObject(0).getString("cwl_name");
+            String runID = result.get(0).getRunId();
+            String cwlFile = result.get(0).getCwlName();
 
             String jsonContent = "{\"run_id\": \"" + runID + "\", \"workflows\": [\"" + cwlFile + "\"]}";
 

src/test/java/nl/esciencecenter/restape/ApeAPITest.java

@@ -5,9 +5,9 @@
 
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
+import java.util.List;
 
 import org.apache.commons.io.FileUtils;
-import org.json.JSONArray;
 import org.json.JSONObject;
 import org.junit.jupiter.api.Test;
 import org.semanticweb.owlapi.model.OWLOntologyCreationException;
@@ -32,7 +32,7 @@ void runSynthesisFail() throws IOException, OWLOntologyCreationException {
                 StandardCharsets.UTF_8);
         JSONObject jsonObject = new JSONObject(content);
         jsonObject.put("solutions", "1");
-        JSONArray result = ApeAPI.runSynthesis(jsonObject, false);
+        List<APEWorkflowMetadata> result = ApeAPI.runSynthesis(jsonObject, false);
         assertTrue(result.isEmpty(), "The encoding should be UNSAT.");
     }
 
@@ -50,7 +50,7 @@ void runSynthesisPass() throws IOException, OWLOntologyCreationException {
                 StandardCharsets.UTF_8);
         JSONObject jsonObject = new JSONObject(content);
         jsonObject.put("solutions", "1");
-        JSONArray result = ApeAPI.runSynthesis(jsonObject, false);
+        List<APEWorkflowMetadata> result = ApeAPI.runSynthesis(jsonObject, false);
         assertFalse(result.isEmpty(), "The encoding should be SAT.");
     }
 
@@ -68,7 +68,7 @@ void runSynthesisAndBenchmarkPass() throws IOException, OWLOntologyCreationExcep
                 StandardCharsets.UTF_8);
         JSONObject jsonObject = new JSONObject(content);
         jsonObject.put("solutions", "1");
-        JSONArray result = ApeAPI.runSynthesis(jsonObject, true);
+        List<APEWorkflowMetadata> result = ApeAPI.runSynthesis(jsonObject, true);
         assertFalse(result.isEmpty(), "The encoding should be SAT.");
     }
 }

src/test/java/nl/esciencecenter/restape/IOUtilsTest.java

@@ -6,7 +6,6 @@
 import java.util.List;
 
 import org.apache.commons.io.FileUtils;
-import org.json.JSONArray;
 import org.json.JSONObject;
 import org.junit.jupiter.api.Test;
 import org.springframework.boot.test.context.SpringBootTest;
@@ -25,10 +24,10 @@ void testZipFilesForLocalExecution() throws Exception {
                             StandardCharsets.UTF_8);
             JSONObject jsonObject = new JSONObject(content);
             jsonObject.put("solutions", "1");
-            JSONArray result = ApeAPI.runSynthesis(jsonObject, false);
+            List<APEWorkflowMetadata> result = ApeAPI.runSynthesis(jsonObject, false);
             assertFalse(result.isEmpty(), "The encoding should be SAT.");
-            String runID = result.getJSONObject(0).getString("run_id");
-            String cwlFile = result.getJSONObject(0).getString("cwl_name");
+            String runID = result.get(0).getRunId();
+            String cwlFile = result.get(0).getCwlName();
 
             CWLZip cwlZip = new CWLZip();
             cwlZip.setRunID(runID);