Document api responses for /v1/bom and /v1/bom/token/{uuid}

src/main/java/org/dependencytrack/resources/v1/BomResource.java

@@ -42,6 +42,8 @@
 import org.dependencytrack.parser.cyclonedx.util.ModelConverter;
 import org.dependencytrack.persistence.QueryManager;
 import org.dependencytrack.resources.v1.vo.BomSubmitRequest;
+import org.dependencytrack.resources.v1.vo.BomSubmitResponse;
+import org.dependencytrack.resources.v1.vo.TokenBeingProcessedResponse;
 import org.glassfish.jersey.media.multipart.BodyPartEntity;
 import org.glassfish.jersey.media.multipart.FormDataBodyPart;
 import org.glassfish.jersey.media.multipart.FormDataMultiPart;
@@ -63,7 +65,6 @@
 import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.Base64;
-import java.util.Collections;
 import java.util.List;
 import java.util.UUID;
 import java.util.stream.Collectors;
@@ -190,7 +191,8 @@ public Response exportComponentAsCycloneDx (
     @Produces(MediaType.APPLICATION_JSON)
     @ApiOperation(
             value = "Upload a supported bill of material format document",
-            notes = "Expects CycloneDX or SPDX (text or RDF) along and a valid project UUID. If a UUID is not specified, than the projectName and projectVersion must be specified. Optionally, if autoCreate is specified and 'true' and the project does not exist, the project will be created. In this scenario, the principal making the request will additionally need the PORTFOLIO_MANAGEMENT or PROJECT_CREATION_UPLOAD permission."
+            notes = "Expects a CycloneDX or SPDX (text or RDF) document along with a valid project UUID. If a UUID is not specified, then the projectName and projectVersion must be specified. Optionally, if autoCreate is specified and 'true' and the project does not exist, the project will be created. In this scenario, the principal making the request will additionally need the PORTFOLIO_MANAGEMENT or PROJECT_CREATION_UPLOAD permission.",
+			response = BomSubmitResponse.class
     )
     @ApiResponses(value = {
             @ApiResponse(code = 401, message = "Unauthorized"),
@@ -233,7 +235,8 @@ public Response uploadBom(BomSubmitRequest request) {
     @Produces(MediaType.APPLICATION_JSON)
     @ApiOperation(
             value = "Upload a supported bill of material format document",
-            notes = "Expects CycloneDX or SPDX (text or RDF) along and a valid project UUID. If a UUID is not specified, than the projectName and projectVersion must be specified. Optionally, if autoCreate is specified and 'true' and the project does not exist, the project will be created. In this scenario, the principal making the request will additionally need the PORTFOLIO_MANAGEMENT or PROJECT_CREATION_UPLOAD permission."
+            notes = "Expects a CycloneDX or SPDX (text or RDF) document along with a valid project UUID. If a UUID is not specified, then the projectName and projectVersion must be specified. Optionally, if autoCreate is specified and 'true' and the project does not exist, the project will be created. In this scenario, the principal making the request will additionally need the PORTFOLIO_MANAGEMENT or PROJECT_CREATION_UPLOAD permission.",
+			response = BomSubmitResponse.class
     )
     @ApiResponses(value = {
             @ApiResponse(code = 401, message = "Unauthorized"),
@@ -274,7 +277,8 @@ public Response uploadBom(@FormDataParam("project") String projectUuid,
     @Produces(MediaType.APPLICATION_JSON)
     @ApiOperation(
             value = "Determines if there are any tasks associated with the token that are being processed, or in the queue to be processed.",
-            notes = "This endpoint is intended to be used in conjunction with uploading a supported BOM document. Upon upload, a token will be returned. The token can then be queried using this endpoint to determine if any tasks (such as vulnerability analysis) is being performed on the BOM. A value of true indicates processing is occurring. A value of false indicates that no processing is occurring for the specified token. However, a value of false also does not confirm the token is valid, only that no processing is associated with the specified token."
+            notes = "This endpoint is intended to be used in conjunction with uploading a supported BOM document. Upon upload, a token will be returned. The token can then be queried using this endpoint to determine if any tasks (such as vulnerability analysis) is being performed on the BOM. A value of true indicates processing is occurring. A value of false indicates that no processing is occurring for the specified token. However, a value of false also does not confirm the token is valid, only that no processing is associated with the specified token.",
+			response = TokenBeingProcessedResponse.class
     )
     @ApiResponses(value = {
             @ApiResponse(code = 401, message = "Unauthorized")
@@ -285,7 +289,7 @@ public Response isTokenBeingProcessed (
             @PathParam("uuid") String uuid) {
 
         final boolean value = Event.isEventBeingProcessed(UUID.fromString(uuid));
-        return Response.ok(Collections.singletonMap("processing", value)).build();
+        return Response.ok(new TokenBeingProcessedResponse(value)).build();
     }
 
     /**
@@ -296,7 +300,7 @@ private Response process(Project project, String encodedBomData) {
             final byte[] decoded = Base64.getDecoder().decode(encodedBomData);
             final BomUploadEvent bomUploadEvent = new BomUploadEvent(project.getUuid(), decoded);
             Event.dispatch(bomUploadEvent);
-            return Response.ok(Collections.singletonMap("token", bomUploadEvent.getChainIdentifier())).build();
+            return Response.ok(new BomSubmitResponse(bomUploadEvent.getChainIdentifier().toString())).build();
         } else {
             return Response.status(Response.Status.NOT_FOUND).entity("The project could not be found.").build();
         }
@@ -315,7 +319,7 @@ private Response process(Project project, List<FormDataBodyPart> artifactParts)
                     // todo: https://github.com/DependencyTrack/dependency-track/issues/130
                     final BomUploadEvent bomUploadEvent = new BomUploadEvent(project.getUuid(), content);
                     Event.dispatch(bomUploadEvent);
-                    return Response.ok(Collections.singletonMap("token", bomUploadEvent.getChainIdentifier())).build();
+                    return Response.ok(new BomSubmitResponse(bomUploadEvent.getChainIdentifier().toString())).build();
                 } catch (IOException e) {
                     return Response.status(Response.Status.BAD_REQUEST).build();
                 }

src/main/java/org/dependencytrack/resources/v1/vo/BomSubmitResponse.java

@@ -0,0 +1,47 @@
+/*
+ * This file is part of Dependency-Track.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) Steve Springett. All Rights Reserved.
+ */
+package org.dependencytrack.resources.v1.vo;
+
+import javax.validation.constraints.NotNull;
+import javax.validation.constraints.Pattern;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Defines a custom response object used when uploading bill-of-material (bom) documents.
+ *
+ * @author Justin Tay
+ * @since 3.5.0
+ */
+public final class BomSubmitResponse {
+
+    @NotNull
+    @Pattern(regexp = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", message = "The token must be a valid 36 character UUID")
+    private final String token;
+
+    @JsonCreator
+    public BomSubmitResponse(@JsonProperty(value = "token", required = true) String token) {
+    	this.token = token;
+    }
+
+    public String getToken() {
+        return token;
+    }
+}

src/main/java/org/dependencytrack/resources/v1/vo/TokenBeingProcessedResponse.java

@@ -0,0 +1,42 @@
+/*
+ * This file is part of Dependency-Track.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) Steve Springett. All Rights Reserved.
+ */
+package org.dependencytrack.resources.v1.vo;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Defines a custom response object used when querying a token for processing status.
+ *
+ * @author Justin Tay
+ * @since 3.5.0
+ */
+public final class TokenBeingProcessedResponse {
+
+    private final boolean processing;
+
+    @JsonCreator
+    public TokenBeingProcessedResponse(@JsonProperty(value = "processing", required = true) boolean processing) {
+    	this.processing = processing;
+    }
+
+	public boolean isProcessing() {
+		return processing;
+	}
+}