TSK-1737: documented API

lib/taskana-core/src/main/java/pro/taskana/common/api/ConfigurationService.java

@@ -3,11 +3,28 @@ package pro.taskana.common.api;
 import java.util.Map;
 import java.util.Optional;
 
+/** The Configuration Service manages all custom configuration options. */
 public interface ConfigurationService {
 
+  /**
+   * Retrieve all custom attributes from the database.
+   *
+   * @return the custom attributes from the database
+   */
   Map<String, Object> getAllCustomAttributes();
 
+  /**
+   * Override all custom attributes with the provided one.
+   *
+   * @param customAttributes the new custom attributes which should be persisted
+   */
   void setAllCustomAttributes(Map<String, ?> customAttributes);
 
+  /**
+   * Retrieve a specific value from all custom attributes.
+   *
+   * @param attribute the attribute key
+   * @return the attribute value or nothing if the attribute does not exist
+   */
   Optional<Object> getValue(String attribute);
 }

rest/taskana-rest-spring/src/docs/asciidoc/rest-api.adoc

@@ -171,6 +171,8 @@ include::{snippets}/TaskanaEngineControllerRestDocTest/getClassificationCategori
 include::{snippets}/TaskanaEngineControllerRestDocTest/getCurrentUserInfoDocTest/auto-section.adoc[]
 include::{snippets}/TaskanaEngineControllerRestDocTest/getHistoryProviderIsEnabledDocTest/auto-section.adoc[]
 include::{snippets}/TaskanaEngineControllerRestDocTest/getCurrentVersionDocTest/auto-section.adoc[]
+include::{snippets}/TaskanaEngineControllerRestDocTest/getCustomConfigurationAttributesDocTest/auto-section.adoc[]
+include::{snippets}/TaskanaEngineControllerRestDocTest/setCustomConfigurationAttributesDocTest/auto-section.adoc[]
 
 == Import / Export
 

rest/taskana-rest-spring/src/main/java/pro/taskana/common/rest/TaskanaEngineController.java

@@ -122,6 +122,12 @@ public class TaskanaEngineController {
     return ResponseEntity.ok(taskanaEngine.isHistoryEnabled());
   }
 
+  /**
+   * This endpoint retrieves the saved custom configuration.
+   *
+   * @title Get custom configuration
+   * @return custom configuration
+   */
   @GetMapping(path = RestEndpoints.URL_CUSTOM_ATTRIBUTES)
   @Transactional(readOnly = true, rollbackFor = Exception.class)
   public ResponseEntity<CustomAttributesRepresentationModel> getCustomAttributes() {
@@ -129,6 +135,13 @@ public class TaskanaEngineController {
     return ResponseEntity.ok(new CustomAttributesRepresentationModel(allCustomAttributes));
   }
 
+  /**
+   * This endpoint overrides the custom configuration.
+   *
+   * @param customAttributes the new custom configuration
+   * @title Set all custom configuration
+   * @return the new custom configuration
+   */
   @PutMapping(path = RestEndpoints.URL_CUSTOM_ATTRIBUTES)
   @Transactional(rollbackFor = Exception.class)
   public ResponseEntity<CustomAttributesRepresentationModel> setCustomAttributes(

rest/taskana-rest-spring/src/main/java/pro/taskana/common/rest/models/CustomAttributesRepresentationModel.java

@@ -7,6 +7,7 @@ import org.springframework.hateoas.RepresentationModel;
 public class CustomAttributesRepresentationModel
     extends RepresentationModel<CustomAttributesRepresentationModel> {
 
+  /** The custom configuration attributes. */
   private final Map<String, Object> customAttributes;
 
   @ConstructorProperties({"customAttributes"})

rest/taskana-rest-spring/src/test/java/pro/taskana/common/rest/TaskanaEngineControllerRestDocTest.java

@@ -1,10 +1,13 @@
 package pro.taskana.common.rest;
 
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
+import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.put;
 
+import java.util.Map;
 import org.junit.jupiter.api.Test;
 import org.springframework.test.web.servlet.result.MockMvcResultMatchers;
 
+import pro.taskana.common.rest.models.CustomAttributesRepresentationModel;
 import pro.taskana.common.test.BaseRestDocTest;
 
 class TaskanaEngineControllerRestDocTest extends BaseRestDocTest {
@@ -55,4 +58,37 @@ class TaskanaEngineControllerRestDocTest extends BaseRestDocTest {
         .perform(get(RestEndpoints.URL_VERSION))
         .andExpect(MockMvcResultMatchers.status().isOk());
   }
+
+  @Test
+  void getCustomConfigurationAttributesDocTest() throws Exception {
+    mockMvc
+        .perform(get(RestEndpoints.URL_CUSTOM_ATTRIBUTES))
+        .andExpect(MockMvcResultMatchers.status().isOk());
+  }
+
+  @Test
+  void setCustomConfigurationAttributesDocTest() throws Exception {
+    CustomAttributesRepresentationModel customAttributes2 =
+        new CustomAttributesRepresentationModel(
+            Map.of(
+                "filter",
+                "{ \"Tasks with state READY\": { \"state\": [\"READY\"]}, "
+                    + "\"Tasks with state CLAIMED\": {\"state\": [\"CLAIMED\"] }}",
+                "schema",
+                Map.of(
+                    "Filter",
+                    Map.of(
+                        "displayName",
+                        "Filter for Task-Priority-Report",
+                        "members",
+                        Map.of(
+                            "filter",
+                            Map.of("displayName", "Filter values", "type", "json", "min", "1"))))));
+
+    mockMvc
+        .perform(
+            put(RestEndpoints.URL_CUSTOM_ATTRIBUTES)
+                .content(objectMapper.writeValueAsString(customAttributes2)))
+        .andExpect(MockMvcResultMatchers.status().isOk());
+  }
 }