feat: introduce first version of REST API for subtasks creation

Author: codescape

docs/changelog.md

@@ -11,7 +11,7 @@ category: Administration
 
 ### [Unreleased]
 
-* ...
+* feat: introduce first version of REST API for subtasks creation
 
 ### [24.06.0] - 2024-06-30
 

docs/rest-api.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: Rest API
+category: User Guide
+---
+
+This page explains how to use the Rest API to create subtasks provided by Multiple Subtasks for Jira.
+
+Please note:
+The Rest API requires a minimum version `24.08.0` of Multiple Subtasks for Jira.
+Please make sure you have updates Multiple Subtasks for Jira to the latest version for full support of all endpoints.
+
+* Table of Contents
+{:toc}
+
+### Create Subtasks `POST /subtasks/{issueKey}`
+
+    Request URL: /rest/multiple-subtasks/1.0/subtasks/{issueKey}
+    Request Method: POST
+    Content-Type: text/plain
+    Accept: application/json, text/plain
+
+Create the subtasks from the payload for the given `issueKey`.
+
+#### Status Codes
+
+| Status | Reason       | Payload                                                                                                    |
+|--------|--------------|------------------------------------------------------------------------------------------------------------|
+| 200    | Success      | The request was successfull and returns a list of created subtasks and all warnings in `application/json`. |
+| 400    | Bad Request  | The request failed and returns an error message in `text/plain`.                                           |
+| 401    | Unauthorized | -                                                                                                          |
+
+#### Example Request
+
+    - Hallo World
+      fixVersion: unknown
+    - Hallo Moon
+      label: rest-api-demo
+
+#### Example Response
+
+    [
+      {
+        "issueKey": "YEAH-43",
+        "issueSummary": "Hallo World",
+        "warnings": [
+          "Invalid fixVersion: unknown"
+        ]
+      },
+      {
+        "issueKey": "YEAH-44",
+        "issueSummary": "Hallo Moon",
+        "warnings": []
+      }
+    ]

src/main/java/de/codescape/jira/plugins/multiplesubtasks/rest/SubtasksResource.java

@@ -0,0 +1,81 @@
+package de.codescape.jira.plugins.multiplesubtasks.rest;
+
+import com.atlassian.jira.issue.IssueManager;
+import com.atlassian.jira.issue.MutableIssue;
+import com.atlassian.jira.permission.ProjectPermissions;
+import com.atlassian.jira.security.JiraAuthenticationContext;
+import com.atlassian.jira.security.PermissionManager;
+import com.atlassian.plugin.spring.scanner.annotation.imports.ComponentImport;
+import de.codescape.jira.plugins.multiplesubtasks.rest.entities.CreatedSubtaskEntity;
+import de.codescape.jira.plugins.multiplesubtasks.service.SubtasksCreationService;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import javax.ws.rs.*;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Response;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * Rest API to create multiple subtasks.
+ *
+ * @since 24.08.0
+ */
+@Path("/subtasks")
+public class SubtasksResource {
+
+    private final JiraAuthenticationContext jiraAuthenticationContext;
+    private final IssueManager issueManager;
+    private final PermissionManager permissionManager;
+    private final SubtasksCreationService subtasksCreationService;
+
+    @Autowired
+    public SubtasksResource(@ComponentImport JiraAuthenticationContext jiraAuthenticationContext,
+                            @ComponentImport IssueManager issueManager,
+                            @ComponentImport PermissionManager permissionManager,
+                            SubtasksCreationService subtasksCreationService) {
+        this.jiraAuthenticationContext = jiraAuthenticationContext;
+        this.issueManager = issueManager;
+        this.permissionManager = permissionManager;
+        this.subtasksCreationService = subtasksCreationService;
+    }
+
+    @POST
+    @Path("/{issue}")
+    @Consumes(MediaType.TEXT_PLAIN)
+    @Produces({MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN})
+    public Response put(@PathParam("issue") String issueKey, String content) {
+        // TODO consider to remove this check because it is already implemented in SubtasksCreationService
+        MutableIssue issue = issueManager.getIssueByCurrentKey(issueKey);
+        if (issue == null) {
+            return Response
+                .status(Response.Status.BAD_REQUEST)
+                .entity("Issue not found")
+                .type(MediaType.TEXT_PLAIN_TYPE)
+                .build();
+        }
+
+        // TODO consider to move this check into SubtasksCreationService
+        if (!jiraAuthenticationContext.isLoggedInUser() &&
+            !permissionManager.hasPermission(ProjectPermissions.CREATE_ISSUES, issue, jiraAuthenticationContext.getLoggedInUser())) {
+            return Response
+                .status(Response.Status.FORBIDDEN)
+                .build();
+        }
+
+        try {
+            List<CreatedSubtaskEntity> createdSubtasks = subtasksCreationService.subtasksFromString(issueKey, content)
+                .stream()
+                .map(CreatedSubtaskEntity::new)
+                .collect(Collectors.toList());
+            return Response.ok(createdSubtasks).build();
+        } catch (RuntimeException e) {
+            return Response
+                .status(Response.Status.BAD_REQUEST)
+                .entity(e.getMessage())
+                .type(MediaType.TEXT_PLAIN_TYPE)
+                .build();
+        }
+    }
+
+}

src/main/java/de/codescape/jira/plugins/multiplesubtasks/rest/entities/CreatedSubtaskEntity.java

@@ -0,0 +1,38 @@
+package de.codescape.jira.plugins.multiplesubtasks.rest.entities;
+
+import de.codescape.jira.plugins.multiplesubtasks.model.CreatedSubtask;
+import org.codehaus.jackson.annotate.JsonIgnoreProperties;
+import org.codehaus.jackson.annotate.JsonProperty;
+import org.codehaus.jackson.annotate.JsonPropertyOrder;
+
+import java.util.List;
+
+/**
+ * JSON entity to transport the created subtask.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonPropertyOrder({"issueKey", "issueSummary", "warnings"})
+public class CreatedSubtaskEntity {
+
+    private final CreatedSubtask createdSubtask;
+
+    public CreatedSubtaskEntity(CreatedSubtask createdSubtask) {
+        this.createdSubtask = createdSubtask;
+    }
+
+    @JsonProperty
+    public String getIssueKey() {
+        return createdSubtask.getIssue().getKey();
+    }
+
+    @JsonProperty
+    public String getIssueSummary() {
+        return createdSubtask.getIssue().getSummary();
+    }
+
+    @JsonProperty
+    public List<String> getWarnings() {
+        return createdSubtask.getWarnings();
+    }
+
+}