Add OpenAPI example values to request objects

Signed-off-by: nscuro <[email protected]>
DependencyTrack · Mar 17, 2024 · 753924d · 753924d
1 parent b5efff7
commit 753924d
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 10 deletions.
diff --git a/docs/_posts/2024-xx-xx-v4.11.0.md b/docs/_posts/2024-xx-xx-v4.11.0.md
@@ -47,6 +47,7 @@ environment variable `BOM_VALIDATION_ENABLED` to `false`.
 * Add auto-generated changelog to GitHub releases - [apiserver/#3502]
 * Bump SPDX license list to v3.23 - [apiserver/#3508]
 * Validate uploaded BOMs against CycloneDX schema prior to processing them - [apiserver/#3522]
+* Add *required permissions* to OpenAPI descriptions of endpoints - [apiserver/#3557]
 * Show component count in projects list - [frontend/#683]
 * Add current *fail*, *warn*, and *info* values to bottom of policy violation metrics - [frontend/#707]
 * Remove unused policy violation widget - [frontend/#710]
@@ -76,6 +77,7 @@ environment variable `BOM_VALIDATION_ENABLED` to `false`.
 * Fix Cargo repository metadata analyzer not being invoked - [apiserver/#3511]
 * Fix type of `purl` fields in Swagger docs - [apiserver/#3512]
 * Fix CI build status badge - [apiserver/#3513]
+* Fix `bom` and `vex` request fields not being visible in OpenAPI spec - [apiserver/#3557]
 * Fix `VUE_APP_SERVER_URL` being ignored - [frontend/#682]
 * Fix visibility of "Vulnerabilities" and "Policy Violations" columns not being toggle-able individually - [frontend/#686]
 * Fix finding search routes - [frontend/#689]
@@ -117,7 +119,7 @@ For a complete list of changes, refer to the respective GitHub milestones:
 We thank all organizations and individuals who contributed to this release, from logging issues to taking part in discussions on GitHub & Slack to testing of fixes.
 
 Special thanks to everyone who contributed code to implement enhancements and fix defects:  
-[@acdha], [@AnthonyMastrean], [@LaVibeX], [@VithikaS], [@baburkin], [@fnxpt], [@kepten], [@leec94],
+[@a5a351e7], [@acdha], [@AnthonyMastrean], [@LaVibeX], [@VithikaS], [@baburkin], [@fnxpt], [@kepten], [@leec94],
 [@lukas-braune], [@malice00], [@mehab], [@mge-mm], [@mikkeschiren], [@mykter], [@rbt-mm],
 [@rkg-mm], [@sahibamittal], [@sebD], [@setchy]
 
@@ -177,6 +179,7 @@ Special thanks to everyone who contributed code to implement enhancements and fi
 [apiserver/#3512]: https://github.com/DependencyTrack/dependency-track/pull/3512
 [apiserver/#3513]: https://github.com/DependencyTrack/dependency-track/pull/3513
 [apiserver/#3522]: https://github.com/DependencyTrack/dependency-track/pull/3522
+[apiserver/#3557]: https://github.com/DependencyTrack/dependency-track/pull/3557
 
 [frontend/#682]: https://github.com/DependencyTrack/frontend/pull/682
 [frontend/#683]: https://github.com/DependencyTrack/frontend/pull/683
@@ -202,6 +205,7 @@ Special thanks to everyone who contributed code to implement enhancements and fi
 [frontend/#752]: https://github.com/DependencyTrack/frontend/pull/752
 [frontend/#768]: https://github.com/DependencyTrack/frontend/pull/768
 
+[@a5a351e7]: https://github.com/a5a351e7
 [@acdha]: https://github.com/acdha
 [@AnthonyMastrean]: https://github.com/AnthonyMastrean
 [@LaVibeX]: https://github.com/LaVibeX

diff --git a/src/main/java/org/dependencytrack/resources/v1/problems/ProblemDetails.java b/src/main/java/org/dependencytrack/resources/v1/problems/ProblemDetails.java
@@ -45,7 +45,8 @@ public class ProblemDetails {
 
     @ApiModelProperty(
             value = "HTTP status code generated by the origin server for this occurrence of the problem",
-            example = "400"
+            example = "400",
+            required = true
     )
     private Integer status;
 
@@ -58,7 +59,8 @@ public class ProblemDetails {
 
     @ApiModelProperty(
             value = "Human-readable explanation specific to this occurrence of the problem",
-            example = "Example detail"
+            example = "Example detail",
+            required = true
     )
     private String detail;
 

diff --git a/src/main/java/org/dependencytrack/resources/v1/vo/BomSubmitRequest.java b/src/main/java/org/dependencytrack/resources/v1/vo/BomSubmitRequest.java
@@ -23,6 +23,7 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import io.swagger.annotations.ApiModelProperty;
 
 import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.NotNull;
@@ -76,13 +77,13 @@ public BomSubmitRequest(String project,
     }
 
     @JsonCreator
-    public BomSubmitRequest(@JsonProperty(value = "project", required = false) String project,
-                            @JsonProperty(value = "projectName", required = false) String projectName,
-                            @JsonProperty(value = "projectVersion", required = false) String projectVersion,
-                            @JsonProperty(value = "autoCreate", required = false) boolean autoCreate,
-                            @JsonProperty(value = "parentUUID", required = false) String parentUUID,
-                            @JsonProperty(value = "parentName", required = false) String parentName,
-                            @JsonProperty(value = "parentVersion", required = false) String parentVersion,
+    public BomSubmitRequest(@JsonProperty(value = "project") String project,
+                            @JsonProperty(value = "projectName") String projectName,
+                            @JsonProperty(value = "projectVersion") String projectVersion,
+                            @JsonProperty(value = "autoCreate") boolean autoCreate,
+                            @JsonProperty(value = "parentUUID") String parentUUID,
+                            @JsonProperty(value = "parentName") String parentName,
+                            @JsonProperty(value = "parentVersion") String parentVersion,
                             @JsonProperty(value = "bom", required = true) String bom) {
         this.project = project;
         this.projectName = projectName;
@@ -94,26 +95,32 @@ public BomSubmitRequest(@JsonProperty(value = "project", required = false) Strin
         this.bom = bom;
     }
 
+    @ApiModelProperty(example = "38640b33-4ba9-4733-bdab-cbfc40c6f8aa")
     public String getProject() {
         return project;
     }
 
+    @ApiModelProperty(example = "Example Application")
     public String getProjectName() {
         return projectName;
     }
 
+    @ApiModelProperty(example = "1.0.0")
     public String getProjectVersion() {
         return projectVersion;
     }
 
+    @ApiModelProperty(example = "5341f53c-611b-4388-9d9c-731026dc5eec")
     public String getParentUUID() {
         return parentUUID;
     }
 
+    @ApiModelProperty(example = "Example Application Parent")
     public String getParentName() {
         return parentName;
     }
 
+    @ApiModelProperty(example = "1.0.0")
     public String getParentVersion() {
         return parentVersion;
     }
@@ -122,6 +129,15 @@ public boolean isAutoCreate() {
         return autoCreate;
     }
 
+    @ApiModelProperty(
+            value = "Base64 encoded BOM",
+            required = true,
+            example = """
+                    ewogICJib21Gb3JtYXQiOiAiQ3ljbG9uZURYIiwKICAic3BlY1ZlcnNpb24iOiAi\
+                    MS40IiwKICAiY29tcG9uZW50cyI6IFsKICAgIHsKICAgICAgInR5cGUiOiAibGli\
+                    cmFyeSIsCiAgICAgICJuYW1lIjogImFjbWUtbGliIiwKICAgICAgInZlcnNpb24i\
+                    OiAiMS4wLjAiCiAgICB9CiAgXQp9"""
+    )
     public String getBom() {
         return bom;
     }