Merge pull request #3728 from nscuro/openapi-v3

Improve OpenAPI v3 integration

pom.xml

@@ -112,6 +112,7 @@
         <lib.packageurl.version>1.5.0</lib.packageurl.version>
         <lib.pebble.version>3.2.2</lib.pebble.version>
         <lib.resilience4j.version>2.2.0</lib.resilience4j.version>
+        <lib.swagger-parser.version>2.1.22</lib.swagger-parser.version>
         <lib.system-rules.version>1.19.0</lib.system-rules.version>
         <lib.testcontainers.version>1.19.8</lib.testcontainers.version>
         <lib.wiremock.version>2.35.2</lib.wiremock.version>
@@ -266,9 +267,10 @@
             <version>${lib.swagger.version}</version>
         </dependency>
         <dependency>
-            <groupId>io.swagger.core.v3</groupId>
-            <artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
-            <version>${lib.swagger.version}</version>
+            <groupId>io.swagger.parser.v3</groupId>
+            <artifactId>swagger-parser</artifactId>
+            <version>${lib.swagger-parser.version}</version>
+            <scope>test</scope>
         </dependency>
 
         <dependency>
@@ -501,6 +503,7 @@
                 <filtering>true</filtering>
                 <includes>
                     <include>application.version</include>
+                    <include>openapi-configuration.yaml</include>
                 </includes>
             </resource>
         </resources>

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

@@ -81,6 +81,7 @@ public class AccessControlResource extends AlpineResource {
     @ApiResponses(value = {
             @ApiResponse(
                     responseCode = "200",
+                    description = "Projects assigned to the specified team",
                     headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of projects", schema = @Schema(format = "integer")),
                     content = @Content(array = @ArraySchema(schema = @Schema(implementation = Project.class)))
             ),
@@ -113,7 +114,7 @@ public Response retrieveProjects (@Parameter(description = "The UUID of the team
             description = "<p>Requires permission <strong>ACCESS_MANAGEMENT</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200"),
+            @ApiResponse(responseCode = "200", description = "Mapping created successfully"),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The UUID of the team or project could not be found"),
             @ApiResponse(responseCode = "409", description = "A mapping with the same team and project already exists")
@@ -151,7 +152,7 @@ public Response addMapping(AclMappingRequest request) {
             description = "<p>Requires permission <strong>ACCESS_MANAGEMENT</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200"),
+            @ApiResponse(responseCode = "200", description = "Mapping removed successfully"),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The UUID of the team or project could not be found"),
     })

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

@@ -78,7 +78,11 @@ public class AnalysisResource extends AlpineResource {
             description = "<p>Requires permission <strong>VIEW_VULNERABILITY</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Analysis.class))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "An analysis trail",
+                    content = @Content(schema = @Schema(implementation = Analysis.class))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The project, component, or vulnerability could not be found")
     })
@@ -126,7 +130,11 @@ public Response retrieveAnalysis(@Parameter(description = "The UUID of the proje
             description = "<p>Requires permission <strong>VULNERABILITY_ANALYSIS</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Analysis.class))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "The created analysis",
+                    content = @Content(schema = @Schema(implementation = Analysis.class))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The project, component, or vulnerability could not be found")
     })

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

@@ -67,7 +67,11 @@ private boolean isBadgeSupportEnabled(final QueryManager qm) {
     @Operation(
             summary = "Returns current metrics for a specific project")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "A badge displaying current vulnerability metrics for a project in SVG format",
+                    content = @Content(schema = @Schema(type = "string"))
+            ),
             @ApiResponse(responseCode = "204", description = "Badge support is disabled. No content will be returned."),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The project could not be found")
@@ -98,7 +102,11 @@ public Response getProjectVulnerabilitiesBadge(
     @Operation(
             summary = "Returns current metrics for a specific project")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "A badge displaying current vulnerability metrics for a project in SVG format",
+                    content = @Content(schema = @Schema(type = "string"))
+            ),
             @ApiResponse(responseCode = "204", description = "Badge support is disabled. No content will be returned."),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The project could not be found")
@@ -131,7 +139,11 @@ public Response getProjectVulnerabilitiesBadge(
     @Operation(
             summary = "Returns a policy violations badge for a specific project")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "A badge displaying current policy violation metrics of a project in SVG format",
+                    content = @Content(schema = @Schema(type = "string"))
+            ),
             @ApiResponse(responseCode = "204", description = "Badge support is disabled. No content will be returned."),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The project could not be found")
@@ -162,7 +174,11 @@ public Response getProjectPolicyViolationsBadge(
     @Operation(
             summary = "Returns a policy violations badge for a specific project")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "A badge displaying current policy violation metrics of a project in SVG format",
+                    content = @Content(schema = @Schema(type = "string"))
+            ),
             @ApiResponse(responseCode = "204", description = "Badge support is disabled. No content will be returned."),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "404", description = "The project could not be found")

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

@@ -101,7 +101,11 @@ public class BomResource extends AlpineResource {
             description = "<p>Requires permission <strong>VIEW_PORTFOLIO</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "Dependency metadata for a project in CycloneDX format",
+                    content = @Content(schema = @Schema(type = "string"))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"),
             @ApiResponse(responseCode = "404", description = "The project could not be found")
@@ -171,7 +175,11 @@ public Response exportProjectAsCycloneDx (
             description = "<p>Requires permission <strong>VIEW_PORTFOLIO</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "Dependency metadata for a specific component in CycloneDX format",
+                    content = @Content(schema = @Schema(type = "string"))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "403", description = "Access to the specified component is forbidden"),
             @ApiResponse(responseCode = "404", description = "The component could not be found")
@@ -237,7 +245,11 @@ public Response exportComponentAsCycloneDx (
             operationId = "UploadBomBase64Encoded"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = BomUploadResponse.class))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "Token to be used for checking BOM processing progress",
+                    content = @Content(schema = @Schema(implementation = BomUploadResponse.class))
+            ),
             @ApiResponse(
                     responseCode = "400",
                     description = "Invalid BOM",
@@ -329,7 +341,11 @@ public Response uploadBom(@Parameter(required = true) BomSubmitRequest request)
             operationId = "UploadBom"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = BomUploadResponse.class))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "Token to be used for checking BOM processing progress",
+                    content = @Content(schema = @Schema(implementation = BomUploadResponse.class))
+            ),
             @ApiResponse(
                     responseCode = "400",
                     description = "Invalid BOM",
@@ -412,7 +428,11 @@ determine if any tasks (such as vulnerability analysis) is being performed on th
                     <p>Requires permission <strong>BOM_UPLOAD</strong></p>
                     <p><strong>Deprecated</strong>. Use <code>/v1/event/token/{uuid}</code> instead.</p>""")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = IsTokenBeingProcessedResponse.class))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "The processing status of the provided token",
+                    content = @Content(schema = @Schema(implementation = IsTokenBeingProcessedResponse.class))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized")
     })
     @PermissionRequired(Permissions.Constants.BOM_UPLOAD)

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

@@ -59,7 +59,11 @@ public class CalculatorResource extends AlpineResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Operation(summary = "Returns the CVSS base score, impact sub-score and exploitability sub-score")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "number"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "The calculated scores",
+                    content = @Content(schema = @Schema(implementation = Score.class))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized")
     })
     public Response getCvssScores(
@@ -80,7 +84,11 @@ public Response getCvssScores(
     @Produces(MediaType.APPLICATION_JSON)
     @Operation(summary = "Returns the OWASP Risk Rating likelihood score, technical impact score and business impact score")
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "number"))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "The calculated scores",
+                    content = @Content(schema = @Schema(implementation = us.springett.owasp.riskrating.Score.class))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized")
     })
     public Response getOwaspRRScores(

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

@@ -63,11 +63,15 @@ public class ComponentPropertyResource extends AbstractConfigPropertyResource {
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     @Operation(
-            summary = "Returns a list of all ComponentProperties for the specified component",
+            summary = "Returns a list of all properties for the specified component",
             description = "<p>Requires permission <strong>VIEW_PORTFOLIO</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ComponentProperty.class)))),
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "A list of all properties for the specified component",
+                    content = @Content(array = @ArraySchema(schema = @Schema(implementation = ComponentProperty.class)))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"),
             @ApiResponse(responseCode = "404", description = "The project could not be found")
@@ -109,7 +113,11 @@ public Response getProperties(
             description = "<p>Requires permission <strong>PORTFOLIO_MANAGEMENT</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = ComponentProperty.class))),
+            @ApiResponse(
+                    responseCode = "201",
+                    description = "The created component",
+                    content = @Content(schema = @Schema(implementation = ComponentProperty.class))
+            ),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "403", description = "Access to the specified component is forbidden"),
             @ApiResponse(responseCode = "404", description = "The component could not be found"),
@@ -167,7 +175,7 @@ public Response createProperty(
             description = "<p>Requires permission <strong>PORTFOLIO_MANAGEMENT</strong></p>"
     )
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "204"),
+            @ApiResponse(responseCode = "204", description = "Property removed successfully"),
             @ApiResponse(responseCode = "401", description = "Unauthorized"),
             @ApiResponse(responseCode = "403", description = "Access to the specified component is forbidden"),
             @ApiResponse(responseCode = "404", description = "The component or component property could not be found"),