diff --git a/pom.xml b/pom.xml index e6934b5a0..2c6b7d06a 100644 --- a/pom.xml +++ b/pom.xml @@ -112,6 +112,7 @@ 3.25.3 1.20.0 2.2.0 + 2.1.22 1.19.0 0.7.0 6.6.2 @@ -298,9 +299,10 @@ ${lib.swagger.version} - io.swagger.core.v3 - swagger-jaxrs2-servlet-initializer-v2 - ${lib.swagger.version} + io.swagger.parser.v3 + swagger-parser + ${lib.swagger-parser.version} + test @@ -550,6 +552,7 @@ true application.version + openapi-configuration.yaml diff --git a/src/main/java/org/dependencytrack/resources/v1/AccessControlResource.java b/src/main/java/org/dependencytrack/resources/v1/AccessControlResource.java index 653e70a9a..822f03bf5 100644 --- a/src/main/java/org/dependencytrack/resources/v1/AccessControlResource.java +++ b/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 = "

Requires permission ACCESS_MANAGEMENT

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = AclMappingRequest.class))), + @ApiResponse(responseCode = "200", description = "Mapping created successfully", content = @Content(schema = @Schema(implementation = AclMappingRequest.class))), @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,6 +152,7 @@ public Response addMapping(AclMappingRequest request) { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

" ) @ApiResponses(value = { + @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"), }) diff --git a/src/main/java/org/dependencytrack/resources/v1/AnalysisResource.java b/src/main/java/org/dependencytrack/resources/v1/AnalysisResource.java index 12b7e5a48..7e295c10c 100644 --- a/src/main/java/org/dependencytrack/resources/v1/AnalysisResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/AnalysisResource.java @@ -81,6 +81,11 @@ public class AnalysisResource extends AlpineResource { description = "

Requires permission VIEW_VULNERABILITY

" ) @ApiResponses(value = { + @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") }) @@ -128,7 +133,11 @@ public Response retrieveAnalysis(@Parameter(description = "The UUID of the proje description = "

Requires permission VULNERABILITY_ANALYSIS or VULNERABILITY_ANALYSIS_UPDATE

" ) @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") }) diff --git a/src/main/java/org/dependencytrack/resources/v1/BadgeResource.java b/src/main/java/org/dependencytrack/resources/v1/BadgeResource.java index ab3002e68..41e8db3aa 100644 --- a/src/main/java/org/dependencytrack/resources/v1/BadgeResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/BadgeResource.java @@ -67,7 +67,11 @@ private boolean isBadgeSupportEnabled(final QueryManager qm) { summary = "Returns current metrics for a specific project" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string", implementation = ProjectMetrics.class))), + @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") @@ -99,7 +103,11 @@ public Response getProjectVulnerabilitiesBadge( summary = "Returns current metrics for a specific project" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string", implementation = ProjectMetrics.class))), + @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") @@ -133,7 +141,11 @@ public Response getProjectVulnerabilitiesBadge( 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") @@ -165,7 +177,11 @@ public Response getProjectPolicyViolationsBadge( 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") diff --git a/src/main/java/org/dependencytrack/resources/v1/BomResource.java b/src/main/java/org/dependencytrack/resources/v1/BomResource.java index 0638de75e..3213b58c1 100644 --- a/src/main/java/org/dependencytrack/resources/v1/BomResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/BomResource.java @@ -109,8 +109,12 @@ public class BomResource extends AlpineResource { description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { + @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 = "200", content = @Content(schema = @Schema(type = "string"))), @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"), @ApiResponse(responseCode = "404", description = "The project could not be found") }) @@ -179,7 +183,11 @@ public Response exportProjectAsCycloneDx( description = "

Requires permission VIEW_PORTFOLIO

" ) @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") @@ -245,9 +253,19 @@ public Response exportComponentAsCycloneDx( operationId = "UploadBomBase64Encoded" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = BomUploadResponse.class))), - @ApiResponse(responseCode = "400", description = "Invalid BOM", content = @Content(schema = @Schema(implementation = InvalidBomProblemDetails.class), - mediaType = ProblemDetails.MEDIA_TYPE_JSON)), + @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", + content = @Content( + schema = @Schema(implementation = InvalidBomProblemDetails.class), + mediaType = ProblemDetails.MEDIA_TYPE_JSON + ) + ), @ApiResponse(responseCode = "400", description = "The uploaded BOM is invalid"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"), @@ -332,11 +350,18 @@ public Response uploadBom(@Parameter(required = true) BomSubmitRequest request) operationId = "UploadBom" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = BomUploadResponse.class))), - @ApiResponse(responseCode = "400", description = "Invalid BOM", content = @Content( - schema = @Schema(implementation = InvalidBomProblemDetails.class), - mediaType = ProblemDetails.MEDIA_TYPE_JSON - ) + @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", + content = @Content( + schema = @Schema(implementation = InvalidBomProblemDetails.class), + mediaType = ProblemDetails.MEDIA_TYPE_JSON + ) ), @ApiResponse(responseCode = "400", description = "The uploaded BOM is invalid"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @@ -419,7 +444,11 @@ determine if any tasks (such as vulnerability analysis) is being performed on th

Requires permission BOM_UPLOAD

Deprecated. Use /v1/event/token/{uuid} instead.

""") @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) @@ -435,7 +464,7 @@ public Response isTokenBeingProcessed( AtomicBoolean hasTerminalStatus = new AtomicBoolean(true); IsTokenBeingProcessedResponse response = new IsTokenBeingProcessedResponse(); workflowStates.stream().forEach(workflowState -> hasTerminalStatus.set(hasTerminalStatus.get() && (workflowState.getStatus() != WorkflowStatus.PENDING - && workflowState.getStatus() != WorkflowStatus.TIMED_OUT))); + && workflowState.getStatus() != WorkflowStatus.TIMED_OUT))); response.setProcessing(!hasTerminalStatus.get()); return Response.ok(response).build(); } diff --git a/src/main/java/org/dependencytrack/resources/v1/CalculatorResource.java b/src/main/java/org/dependencytrack/resources/v1/CalculatorResource.java index f93bbcbb9..7e885c5f5 100644 --- a/src/main/java/org/dependencytrack/resources/v1/CalculatorResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/CalculatorResource.java @@ -57,11 +57,13 @@ public class CalculatorResource extends AlpineResource { @GET @Path("/cvss") @Produces(MediaType.APPLICATION_JSON) - @Operation( - summary = "Returns the CVSS base score, impact sub-score and exploitability sub-score" - ) + @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,11 +82,13 @@ public Response getCvssScores( @GET @Path("/owasp") @Produces(MediaType.APPLICATION_JSON) - @Operation( - summary = "Returns the OWASP Risk Rating likelihood score, technical impact score and business impact score" - ) + @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( diff --git a/src/main/java/org/dependencytrack/resources/v1/ComponentPropertyResource.java b/src/main/java/org/dependencytrack/resources/v1/ComponentPropertyResource.java index 698fcf752..adde6482f 100644 --- a/src/main/java/org/dependencytrack/resources/v1/ComponentPropertyResource.java +++ b/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 = "

Requires permission VIEW_PORTFOLIO

" ) @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 = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_CREATE

" ) @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 = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_DELETE

" ) @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"), diff --git a/src/main/java/org/dependencytrack/resources/v1/ComponentResource.java b/src/main/java/org/dependencytrack/resources/v1/ComponentResource.java index 3c71c445d..f0d50c721 100644 --- a/src/main/java/org/dependencytrack/resources/v1/ComponentResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/ComponentResource.java @@ -110,6 +110,7 @@ public class ComponentResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all components for a given project", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of components", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = Component.class))) ), @@ -148,7 +149,11 @@ public Response getAllComponents( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Component.class))), + @ApiResponse( + responseCode = "200", + description = "A component", + content = @Content(schema = @Schema(implementation = Component.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") @@ -198,7 +203,11 @@ public Response getComponentByUuid( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = IntegrityMetaComponent.class))), + @ApiResponse( + responseCode = "200", + description = "Integrity metadata of the component", + content = @Content(schema = @Schema(implementation = IntegrityMetaComponent.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The integrity meta information for the specified component cannot be found"), @ApiResponse(responseCode = "400", description = "The package url being queried for is invalid") @@ -237,7 +246,11 @@ public Response getIntegrityMetaComponent( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = IntegrityAnalysis.class))), + @ApiResponse( + responseCode = "200", + description = "Integrity metadata of the component", + content = @Content(schema = @Schema(implementation = IntegrityAnalysis.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The integrity analysis information for the specified component cannot be found"), }) @@ -265,8 +278,12 @@ public Response getIntegrityStatus( ) @PaginatedApi @ApiResponses(value = { - @ApiResponse(responseCode = "200", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of components", schema = @Schema(format = "integer")), - content = @Content(array = @ArraySchema(schema = @Schema(implementation = Component.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of components that have the specified component identity", + headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of components", schema = @Schema(format = "integer")), + content = @Content(array = @ArraySchema(schema = @Schema(implementation = Component.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO) @@ -325,9 +342,12 @@ public Response getComponentByIdentity(@Parameter(description = "The group of th ) @PaginatedApi @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Component.class))), - headers = @Header(description = "The total number of components", name = TOTAL_COUNT_HEADER, schema = @Schema(format = "integer") - )), + @ApiResponse( + responseCode = "200", + description = "A list of components that have the specified hash value", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = Component.class))), + headers = @Header(description = "The total number of components", name = TOTAL_COUNT_HEADER, schema = @Schema(format = "integer")) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO) @@ -349,8 +369,11 @@ public Response getComponentByHash( description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(content = @Content(schema = @Schema(implementation = Component.class)), - responseCode = "201"), + @ApiResponse( + responseCode = "201", + description = "The created component", + content = @Content(schema = @Schema(implementation = Component.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") @@ -470,7 +493,11 @@ public Response createComponent(@Parameter(description = "The UUID of the projec description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = Component.class))), + @ApiResponse( + responseCode = "200", + description = "The updated component", + content = @Content(schema = @Schema(implementation = Component.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to the specified component is forbidden"), @ApiResponse(responseCode = "404", description = "The UUID of the component could not be found"), @@ -590,7 +617,7 @@ public Response updateComponent(Component jsonComponent) { description = "

Requires permission PORTFOLIO_MANAGEMENT

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Component removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to the specified component is forbidden"), @ApiResponse(responseCode = "404", description = "The UUID of the component could not be found") @@ -621,7 +648,7 @@ public Response deleteComponent( description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Identification requested successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.SYSTEM_CONFIGURATION, Permissions.Constants.SYSTEM_CONFIGURATION_READ}) @@ -638,8 +665,11 @@ public Response identifyInternalComponents() { description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", - content = @Content(schema = @Schema(type = "object"))), + @ApiResponse( + responseCode = "200", + description = "The expanded dependency graph to every occurrence of a component", + content = @Content(schema = @Schema(type = "object")) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"), @ApiResponse(responseCode = "404", description = "- The UUID of the project could not be found\n- The UUID of the component could not be found") diff --git a/src/main/java/org/dependencytrack/resources/v1/ConfigPropertyResource.java b/src/main/java/org/dependencytrack/resources/v1/ConfigPropertyResource.java index 74969c369..ffa940a2c 100644 --- a/src/main/java/org/dependencytrack/resources/v1/ConfigPropertyResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/ConfigPropertyResource.java @@ -64,7 +64,11 @@ public class ConfigPropertyResource extends AbstractConfigPropertyResource { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConfigProperty.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of all ConfigProperties for the specified groupName", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConfigProperty.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.SYSTEM_CONFIGURATION, Permissions.Constants.SYSTEM_CONFIGURATION_READ}) @@ -92,7 +96,11 @@ public Response getConfigProperties() { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = ConfigProperty.class))), + @ApiResponse( + responseCode = "200", + description = "The updated config property", + content = @Content(schema = @Schema(implementation = ConfigProperty.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The config property could not be found"), }) @@ -114,11 +122,16 @@ public Response updateConfigProperty(ConfigProperty json) { @Path("aggregate") @Consumes(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON) - @Operation(summary = "Updates an array of config properties", + @Operation( + summary = "Updates an array of config properties", description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConfigProperty.class)))), + @ApiResponse( + responseCode = "200", + description = "The updated config properties", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConfigProperty.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "One or more config properties could not be found"), }) diff --git a/src/main/java/org/dependencytrack/resources/v1/CweResource.java b/src/main/java/org/dependencytrack/resources/v1/CweResource.java index 1586d8685..a5a9a0739 100644 --- a/src/main/java/org/dependencytrack/resources/v1/CweResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/CweResource.java @@ -62,6 +62,7 @@ public class CweResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all CWEs", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of CWEs", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = Cwe.class))) ), @@ -79,7 +80,11 @@ public Response getCwes() { summary = "Returns a specific CWE" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Cwe.class))), + @ApiResponse( + responseCode = "200", + description = "A CWE matching the provided ID", + content = @Content(schema = @Schema(implementation = Cwe.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The CWE could not be found") }) diff --git a/src/main/java/org/dependencytrack/resources/v1/DependencyGraphResource.java b/src/main/java/org/dependencytrack/resources/v1/DependencyGraphResource.java index c61d40287..e62ac02c6 100644 --- a/src/main/java/org/dependencytrack/resources/v1/DependencyGraphResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/DependencyGraphResource.java @@ -81,7 +81,11 @@ public class DependencyGraphResource extends AlpineResource { description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyGraphResponse.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of specific components and services from project UUID", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyGraphResponse.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to a specified component is forbidden"), @ApiResponse(responseCode = "404", description = "Any component can be found"), @@ -119,7 +123,11 @@ public Response getComponentsAndServicesByProjectUuid(@Parameter(description = " description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyGraphResponse.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of specific components and services from component UUID", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyGraphResponse.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to a specified component is forbidden"), @ApiResponse(responseCode = "404", description = "Any component can be found"), diff --git a/src/main/java/org/dependencytrack/resources/v1/EventResource.java b/src/main/java/org/dependencytrack/resources/v1/EventResource.java index 5dd155c16..df75bf50e 100644 --- a/src/main/java/org/dependencytrack/resources/v1/EventResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/EventResource.java @@ -72,7 +72,11 @@ public class EventResource extends AlpineResource {

""" ) @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") }) public Response isTokenBeingProcessed( diff --git a/src/main/java/org/dependencytrack/resources/v1/FindingResource.java b/src/main/java/org/dependencytrack/resources/v1/FindingResource.java index 2de146f60..64edd2f18 100644 --- a/src/main/java/org/dependencytrack/resources/v1/FindingResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/FindingResource.java @@ -97,8 +97,12 @@ public class FindingResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all findings for a specific project, or a SARIF file", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of findings", schema = @Schema(format = "integer")), - content = @Content(array = @ArraySchema(schema = @Schema(implementation = Finding.class))) + content = { + @Content(array = @ArraySchema(schema = @Schema(implementation = Finding.class)), mediaType = MediaType.APPLICATION_JSON), + @Content(schema = @Schema(type = "string"), mediaType = MEDIA_TYPE_SARIF_JSON) + } ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"), @@ -150,7 +154,11 @@ public Response getFindingsByProject(@Parameter(description = "The UUID of the p description = "

Requires permission VIEW_VULNERABILITY

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(type = "string"))), + @ApiResponse( + responseCode = "200", + description = "The findings for the specified project as FPF", + 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") @@ -183,6 +191,7 @@ public Response exportFindingsByProject(@Parameter(description = "The UUID of th description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_CREATE

" ) @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "Analysis triggered successfully"), @ApiResponse(responseCode = "304", description = "Analysis is already in progress"), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @@ -206,7 +215,11 @@ public Response analyzePortfolio() { description = "

Requires permission VIEW_VULNERABILITY

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = BomUploadResponse.class))), + @ApiResponse( + responseCode = "200", + description = "Token to be used for checking analysis progress", + content = @Content(schema = @Schema(implementation = BomUploadResponse.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") @@ -246,6 +259,7 @@ public Response analyzeProject( @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all findings", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of findings", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = Finding.class))) ), @@ -312,6 +326,7 @@ public Response getAllFindings(@Parameter(description = "Show inactive projects" @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all findings grouped by vulnerability", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of findings", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = Finding.class))) ), diff --git a/src/main/java/org/dependencytrack/resources/v1/IntegrationResource.java b/src/main/java/org/dependencytrack/resources/v1/IntegrationResource.java index d85ac6666..cf6aa8a7b 100644 --- a/src/main/java/org/dependencytrack/resources/v1/IntegrationResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/IntegrationResource.java @@ -58,6 +58,7 @@ public class IntegrationResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all ecosystems in OSV", content = @Content(array = @ArraySchema(schema = @Schema(type = "string"))) ), @ApiResponse(responseCode = "401", description = "Unauthorized") @@ -79,6 +80,7 @@ public Response getAllEcosystems() { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of available inactive ecosystems in OSV to be selected by user", content = @Content(array = @ArraySchema(schema = @Schema(type = "string"))) ), @ApiResponse(responseCode = "401", description = "Unauthorized") diff --git a/src/main/java/org/dependencytrack/resources/v1/LdapResource.java b/src/main/java/org/dependencytrack/resources/v1/LdapResource.java index 94a023b07..3e96e9035 100644 --- a/src/main/java/org/dependencytrack/resources/v1/LdapResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/LdapResource.java @@ -88,6 +88,7 @@ public class LdapResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "DNs of all accessible groups within the directory", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of ldap groups that match the specified search criteria", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(type = "string"))) ), @@ -134,7 +135,11 @@ public Response retrieveLdapGroups() { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = MappedLdapGroup.class)))), + @ApiResponse( + responseCode = "200", + description = "DNs of all groups mapped to the specified team", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = MappedLdapGroup.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the team could not be found"), }) @@ -160,7 +165,11 @@ public Response retrieveLdapGroups(@Parameter(description = "The UUID of the tea description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = MappedLdapGroup.class))), + @ApiResponse( + responseCode = "200", + description = "The created mapping", + content = @Content(schema = @Schema(implementation = MappedLdapGroup.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the team could not be found"), @ApiResponse(responseCode = "409", description = "A mapping with the same team and dn already exists") @@ -195,7 +204,7 @@ public Response addMapping(MappedLdapGroupRequest request) { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Mapping removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the mapping could not be found"), }) diff --git a/src/main/java/org/dependencytrack/resources/v1/LicenseGroupResource.java b/src/main/java/org/dependencytrack/resources/v1/LicenseGroupResource.java index f3d64559f..88b6dcf14 100644 --- a/src/main/java/org/dependencytrack/resources/v1/LicenseGroupResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/LicenseGroupResource.java @@ -77,6 +77,7 @@ public class LicenseGroupResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all license groups", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of license groups", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = LicenseGroup.class))) ), @@ -98,6 +99,11 @@ public Response getLicenseGroups() { description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_READ

" ) @ApiResponses(value = { + @ApiResponse( + responseCode = "200", + description = "A specific license group", + content = @Content(schema = @Schema(implementation = LicenseGroup.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The license group could not be found") }) @@ -123,7 +129,11 @@ public Response getLicenseGroup( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = LicenseGroup.class))), + @ApiResponse( + responseCode = "201", + description = "The created license group", + content = @Content(schema = @Schema(implementation = LicenseGroup.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "409", description = "A license group with the specified name already exists") }) @@ -153,7 +163,11 @@ public Response createLicenseGroup(LicenseGroup jsonLicenseGroup) { description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = LicenseGroup.class))), + @ApiResponse( + responseCode = "200", + description = "The updated license group", + content = @Content(schema = @Schema(implementation = LicenseGroup.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The license group could not be found") }) @@ -184,7 +198,7 @@ public Response updateLicenseGroup(LicenseGroup jsonLicenseGroup) { description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "License group removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the license group could not be found") }) @@ -212,7 +226,11 @@ public Response deleteLicenseGroup( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = LicenseGroup.class))), + @ApiResponse( + responseCode = "200", + description = "The updated license group", + content = @Content(schema = @Schema(implementation = LicenseGroup.class)) + ), @ApiResponse(responseCode = "304", description = "The license group already has the specified license assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The license group or license could not be found") @@ -252,7 +270,11 @@ public Response addLicenseToLicenseGroup( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = LicenseGroup.class))), + @ApiResponse( + responseCode = "200", + description = "The updated license group", + content = @Content(schema = @Schema(implementation = LicenseGroup.class)) + ), @ApiResponse(responseCode = "304", description = "The license is not a member with the license group"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The license group or license could not be found") diff --git a/src/main/java/org/dependencytrack/resources/v1/LicenseResource.java b/src/main/java/org/dependencytrack/resources/v1/LicenseResource.java index 0b1bf42e1..b661bd3bd 100644 --- a/src/main/java/org/dependencytrack/resources/v1/LicenseResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/LicenseResource.java @@ -72,7 +72,9 @@ public class LicenseResource extends AlpineResource { ) @PaginatedApi @ApiResponses(value = { - @ApiResponse(responseCode = "200", + @ApiResponse( + responseCode = "200", + description = "A list of all licenses with complete metadata for each license", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of licenses", schema = @Schema(format = "integeger")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = License.class))) ), @@ -92,9 +94,12 @@ public Response getLicenses() { summary = "Returns a concise listing of all licenses" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", + @ApiResponse( + responseCode = "200", + description = "A concise listing of all licenses", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of licenses", schema = @Schema(format = "integer")), - content = @Content(array = @ArraySchema(schema = @Schema(implementation = License.class)))), + content = @Content(array = @ArraySchema(schema = @Schema(implementation = License.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) public Response getLicenseListing() { @@ -111,7 +116,11 @@ public Response getLicenseListing() { summary = "Returns a specific license" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = License.class))), + @ApiResponse( + responseCode = "200", + description = "A specific license", + content = @Content(schema = @Schema(implementation = License.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The license could not be found") }) @@ -135,7 +144,11 @@ public Response getLicense( description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = License.class))), + @ApiResponse( + responseCode = "201", + description = "The created license", + content = @Content(schema = @Schema(implementation = License.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "409", description = "A license with the specified ID already exists.") }) @@ -166,7 +179,7 @@ public Response createLicense(License jsonLicense) { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "License removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The license could not be found"), @ApiResponse(responseCode = "409", description = "Only custom licenses can be deleted.") diff --git a/src/main/java/org/dependencytrack/resources/v1/MetricsResource.java b/src/main/java/org/dependencytrack/resources/v1/MetricsResource.java index 073ccc325..f0af0b8cb 100644 --- a/src/main/java/org/dependencytrack/resources/v1/MetricsResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/MetricsResource.java @@ -77,7 +77,11 @@ public class MetricsResource extends AlpineResource { description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = VulnerabilityMetrics.class)))), + @ApiResponse( + responseCode = "200", + description = "The sum of all vulnerabilities in the database by year and month", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = VulnerabilityMetrics.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO) @@ -96,7 +100,11 @@ public Response getVulnerabilityMetrics() { description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PortfolioMetrics.class))), + @ApiResponse( + responseCode = "200", + description = "Current metrics for the entire portfolio", + content = @Content(schema = @Schema(implementation = PortfolioMetrics.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO) @@ -116,7 +124,11 @@ public Response getPortfolioCurrentMetrics() {

Date format must be YYYYMMDD

Requires permission VIEW_PORTFOLIO

""") @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = PortfolioMetrics.class)))), + @ApiResponse( + responseCode = "200", + description = "Historical metrics for the entire portfolio from a specific date", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = PortfolioMetrics.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO) @@ -142,7 +154,11 @@ public Response getPortfolioMetricsSince( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = PortfolioMetrics.class)))), + @ApiResponse( + responseCode = "200", + description = "X days of historical metrics for the entire portfolio", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = PortfolioMetrics.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired(Permissions.Constants.VIEW_PORTFOLIO) @@ -165,7 +181,7 @@ public Response getPortfolioMetricsXDays( description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PortfolioMetrics.class))), + @ApiResponse(responseCode = "200", description = "Refresh requested successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.PORTFOLIO_MANAGEMENT, Permissions.Constants.PORTFOLIO_MANAGEMENT_READ}) @@ -182,7 +198,11 @@ public Response RefreshPortfolioMetrics() { description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = ProjectMetrics.class))), + @ApiResponse( + responseCode = "200", + description = "Current metrics for a specific project", + content = @Content(schema = @Schema(implementation = ProjectMetrics.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") @@ -216,7 +236,11 @@ public Response getProjectCurrentMetrics(

Requires permission VIEW_PORTFOLIO

""" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ProjectMetrics.class)))), + @ApiResponse( + responseCode = "200", + description = "Historical metrics for a specific project from a specific date", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = ProjectMetrics.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") @@ -240,8 +264,12 @@ public Response getProjectMetricsSince( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { + @ApiResponse( + responseCode = "200", + description = "X days of historical metrics for a specific project", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = ProjectMetrics.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ProjectMetrics.class)))), @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"), @ApiResponse(responseCode = "404", description = "The project could not be found") }) @@ -264,6 +292,7 @@ public Response getProjectMetricsXDays( description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_READ

" ) @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "Refresh requested successfully"), @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") @@ -295,7 +324,11 @@ public Response RefreshProjectMetrics( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = DependencyMetrics.class))), + @ApiResponse( + responseCode = "200", + description = "Current metrics for a specific component", + content = @Content(schema = @Schema(implementation = DependencyMetrics.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") @@ -329,7 +362,11 @@ public Response getComponentCurrentMetrics(

Requires permission VIEW_PORTFOLIO

""" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyMetrics.class)))), + @ApiResponse( + responseCode = "200", + description = "Historical metrics for a specific component from a specific date", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyMetrics.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") @@ -356,7 +393,11 @@ public Response getComponentMetricsSince( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyMetrics.class)))), + @ApiResponse( + responseCode = "200", + description = "X days of historical metrics for a specific component", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = DependencyMetrics.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") @@ -380,6 +421,7 @@ public Response getComponentMetricsXDays( description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_READ

" ) @ApiResponses(value = { + @ApiResponse(responseCode = "200", description = "Refresh requested successfully"), @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") diff --git a/src/main/java/org/dependencytrack/resources/v1/NotificationPublisherResource.java b/src/main/java/org/dependencytrack/resources/v1/NotificationPublisherResource.java index 3d41d6c1f..f9196cb94 100644 --- a/src/main/java/org/dependencytrack/resources/v1/NotificationPublisherResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/NotificationPublisherResource.java @@ -77,7 +77,11 @@ public class NotificationPublisherResource extends AlpineResource { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = NotificationPublisher.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of all notification publishers", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = NotificationPublisher.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.SYSTEM_CONFIGURATION, Permissions.Constants.SYSTEM_CONFIGURATION_READ}) @@ -96,7 +100,11 @@ public Response getAllNotificationPublishers() { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = NotificationPublisher.class))), + @ApiResponse( + responseCode = "201", + description = "The created notification publisher", + content = @Content(schema = @Schema(implementation = NotificationPublisher.class)) + ), @ApiResponse(responseCode = "400", description = "Invalid notification class or trying to modify a default publisher"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "409", description = "Conflict with an existing publisher's name") @@ -143,7 +151,11 @@ public Response createNotificationPublisher(NotificationPublisher jsonNotificati description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = NotificationPublisher.class))), + @ApiResponse( + responseCode = "200", + description = "The updated notification publisher", + content = @Content(schema = @Schema(implementation = NotificationPublisher.class)) + ), @ApiResponse(responseCode = "400", description = "Invalid notification class or trying to modify a default publisher"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The notification publisher could not be found"), @@ -203,7 +215,7 @@ public Response updateNotificationPublisher(NotificationPublisher jsonNotificati description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Notification publisher removed successfully"), @ApiResponse(responseCode = "400", description = "Deleting a default notification publisher is forbidden"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the notification publisher could not be found") @@ -236,7 +248,7 @@ public Response deleteNotificationPublisher(@Parameter(description = "The UUID o description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200"), + @ApiResponse(responseCode = "200", description = "Default templates restored successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.SYSTEM_CONFIGURATION, Permissions.Constants.SYSTEM_CONFIGURATION_CREATE}) diff --git a/src/main/java/org/dependencytrack/resources/v1/NotificationRuleResource.java b/src/main/java/org/dependencytrack/resources/v1/NotificationRuleResource.java index fc3df4430..bde39188d 100644 --- a/src/main/java/org/dependencytrack/resources/v1/NotificationRuleResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/NotificationRuleResource.java @@ -81,6 +81,7 @@ public class NotificationRuleResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all notification rules", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of notification rules", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = NotificationRule.class))) ), @@ -101,7 +102,11 @@ public Response getAllNotificationRules() { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = NotificationRule.class))), + @ApiResponse( + responseCode = "201", + description = "The created notification rule", + content = @Content(schema = @Schema(implementation = NotificationRule.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the notification publisher could not be found") }) @@ -137,7 +142,11 @@ public Response createNotificationRule(NotificationRule jsonRule) { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = NotificationRule.class))), + @ApiResponse( + responseCode = "200", + description = "The updated notification rule", + content = @Content(schema = @Schema(implementation = NotificationRule.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the notification rule could not be found") }) @@ -168,7 +177,7 @@ public Response updateNotificationRule(NotificationRule jsonRule) { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Notification rule removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the notification rule could not be found") }) @@ -193,7 +202,11 @@ public Response deleteNotificationRule(NotificationRule jsonRule) { description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = NotificationRule.class))), + @ApiResponse( + responseCode = "200", + description = "The updated notification rule", + content = @Content(schema = @Schema(implementation = NotificationRule.class)) + ), @ApiResponse(responseCode = "304", description = "The rule already has the specified project assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The notification rule or project could not be found") @@ -234,7 +247,11 @@ public Response addProjectToRule( description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = NotificationRule.class))), + @ApiResponse( + responseCode = "200", + description = "The updated notification rule", + content = @Content(schema = @Schema(implementation = NotificationRule.class)) + ), @ApiResponse(responseCode = "304", description = "The rule does not have the specified project assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The notification rule or project could not be found") @@ -275,7 +292,11 @@ public Response removeProjectFromRule( description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = NotificationRule.class))), + @ApiResponse( + responseCode = "200", + description = "The updated notification rule", + content = @Content(schema = @Schema(implementation = NotificationRule.class)) + ), @ApiResponse(responseCode = "304", description = "The rule already has the specified team assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The notification rule or team could not be found") @@ -316,7 +337,11 @@ public Response addTeamToRule( description = "

Requires permission SYSTEM_CONFIGURATION or SYSTEM_CONFIGURATION_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = NotificationRule.class))), + @ApiResponse( + responseCode = "200", + description = "The updated notification rule", + content = @Content(schema = @Schema(implementation = NotificationRule.class)) + ), @ApiResponse(responseCode = "304", description = "The rule does not have the specified team assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The notification rule or team could not be found") diff --git a/src/main/java/org/dependencytrack/resources/v1/OidcResource.java b/src/main/java/org/dependencytrack/resources/v1/OidcResource.java index 2ecc4ff80..735f89c97 100644 --- a/src/main/java/org/dependencytrack/resources/v1/OidcResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/OidcResource.java @@ -74,8 +74,11 @@ public class OidcResource extends AlpineResource { @GET @Path("/available") @Produces(MediaType.TEXT_PLAIN) - @Operation( - summary = "Indicates if OpenID Connect is available for this application" + @Operation(summary = "Indicates if OpenID Connect is available for this application") + @ApiResponse( + responseCode = "200", + description = "Whether OpenID Connect is available", + content = @Content(schema = @Schema(type = "boolean")) ) @AuthenticationNotRequired public Response isAvailable() { @@ -90,7 +93,11 @@ public Response isAvailable() { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = OidcGroup.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of all groups", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = OidcGroup.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.ACCESS_MANAGEMENT, Permissions.Constants.ACCESS_MANAGEMENT_READ}) @@ -110,7 +117,11 @@ public Response retrieveGroups() { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = OidcGroup.class))), + @ApiResponse( + responseCode = "201", + description = "The created group", + content = @Content(schema = @Schema(implementation = OidcGroup.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.ACCESS_MANAGEMENT, Permissions.Constants.ACCESS_MANAGEMENT_CREATE}) @@ -140,7 +151,11 @@ public Response createGroup(final OidcGroup jsonGroup) { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = OidcGroup.class))), + @ApiResponse( + responseCode = "200", + description = "The updated group", + content = @Content(schema = @Schema(implementation = OidcGroup.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.ACCESS_MANAGEMENT, Permissions.Constants.ACCESS_MANAGEMENT_UPDATE}) @@ -172,7 +187,7 @@ public Response updateGroup(final OidcGroup jsonGroup) { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Group removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The group could not be found") }) @@ -200,7 +215,11 @@ public Response deleteGroup(@Parameter(description = "The UUID of the group to d description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Team.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of teams associated with the specified group", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = Team.class))) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the mapping could not be found"), }) @@ -229,7 +248,11 @@ public Response retrieveTeamsMappedToGroup(@Parameter(description = "The UUID of description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = MappedOidcGroup.class))), + @ApiResponse( + responseCode = "200", + description = "The created mapping", + content = @Content(schema = @Schema(implementation = MappedOidcGroup.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the team or group could not be found"), @ApiResponse(responseCode = "409", description = "A mapping with the same team and group name already exists") @@ -271,7 +294,7 @@ public Response addMapping(final MappedOidcGroupRequest request) { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Mapping removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the mapping could not be found"), }) @@ -298,7 +321,7 @@ public Response deleteMappingByUuid(@Parameter(description = "The UUID of the ma description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Mapping removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the mapping could not be found"), }) diff --git a/src/main/java/org/dependencytrack/resources/v1/PermissionResource.java b/src/main/java/org/dependencytrack/resources/v1/PermissionResource.java index fc4875b9d..19d305a1d 100644 --- a/src/main/java/org/dependencytrack/resources/v1/PermissionResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/PermissionResource.java @@ -72,7 +72,11 @@ public class PermissionResource extends AlpineResource { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Permissions.class))), + @ApiResponse( + responseCode = "200", + description = "A list of all permissions", + content = @Content(schema = @Schema(implementation = Permissions.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized") }) @PermissionRequired({Permissions.Constants.ACCESS_MANAGEMENT, Permissions.Constants.ACCESS_MANAGEMENT_READ}) @@ -92,7 +96,11 @@ public Response getAllPermissions() { description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = UserPrincipal.class))), + @ApiResponse( + responseCode = "200", + description = "The updated user", + content = @Content(schema = @Schema(implementation = UserPrincipal.class)) + ), @ApiResponse(responseCode = "304", description = "The user already has the specified permission assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The user could not be found") @@ -133,7 +141,11 @@ public Response addPermissionToUser( description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = UserPrincipal.class))), + @ApiResponse( + responseCode = "200", + description = "The updated user", + content = @Content(schema = @Schema(implementation = UserPrincipal.class)) + ), @ApiResponse(responseCode = "304", description = "The user already has the specified permission assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The user could not be found") @@ -173,7 +185,11 @@ public Response removePermissionFromUser( description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Team.class))), + @ApiResponse( + responseCode = "200", + description = "The updated team", + content = @Content(schema = @Schema(implementation = Team.class)) + ), @ApiResponse(responseCode = "304", description = "The team already has the specified permission assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The team could not be found") @@ -213,7 +229,11 @@ public Response addPermissionToTeam( description = "

Requires permission ACCESS_MANAGEMENT or ACCESS_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204", content = @Content(schema = @Schema(implementation = Team.class))), + @ApiResponse( + responseCode = "200", + description = "The updated team", + content = @Content(schema = @Schema(implementation = Team.class)) + ), @ApiResponse(responseCode = "304", description = "The team already has the specified permission assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The team could not be found") diff --git a/src/main/java/org/dependencytrack/resources/v1/PolicyConditionResource.java b/src/main/java/org/dependencytrack/resources/v1/PolicyConditionResource.java index 20f9b644e..28f941859 100644 --- a/src/main/java/org/dependencytrack/resources/v1/PolicyConditionResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/PolicyConditionResource.java @@ -81,7 +81,11 @@ public class PolicyConditionResource extends AlpineResource { description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = PolicyCondition.class))), + @ApiResponse( + responseCode = "201", + description = "The created policy condition", + content = @Content(schema = @Schema(implementation = PolicyCondition.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the policy could not be found") }) @@ -117,8 +121,11 @@ public Response createPolicyCondition( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PolicyCondition.class))), - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = PolicyCondition.class))), + @ApiResponse( + responseCode = "200", + description = "The updated policy condition", + content = @Content(schema = @Schema(implementation = PolicyCondition.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the policy condition could not be found") }) @@ -149,7 +156,7 @@ public Response updatePolicyCondition(PolicyCondition jsonPolicyCondition) { description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Policy condition removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the policy condition could not be found") }) diff --git a/src/main/java/org/dependencytrack/resources/v1/PolicyResource.java b/src/main/java/org/dependencytrack/resources/v1/PolicyResource.java index 9a4aef9f0..e0dd12bad 100644 --- a/src/main/java/org/dependencytrack/resources/v1/PolicyResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/PolicyResource.java @@ -77,6 +77,7 @@ public class PolicyResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all policies", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of policies", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = Policy.class))) ), @@ -98,7 +99,11 @@ public Response getPolicies() { , description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Policy.class))), + @ApiResponse( + responseCode = "200", + description = "A specific policy", + content = @Content(schema = @Schema(implementation = Policy.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The policy could not be found") }) @@ -124,7 +129,11 @@ public Response getPolicy( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_CREATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = Policy.class))), + @ApiResponse( + responseCode = "201", + description = "The created policy", + content = @Content(schema = @Schema(implementation = Policy.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "409", description = "A policy with the specified name already exists") }) @@ -164,7 +173,11 @@ public Response createPolicy(Policy jsonPolicy) { description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Policy.class))), + @ApiResponse( + responseCode = "200", + description = "The updated policy", + content = @Content(schema = @Schema(implementation = Policy.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The policy could not be found") }) @@ -198,7 +211,7 @@ public Response updatePolicy(Policy jsonPolicy) { , description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Policy removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The UUID of the policy could not be found") }) @@ -226,7 +239,11 @@ public Response deletePolicy( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Policy.class))), + @ApiResponse( + responseCode = "200", + description = "The updated policy", + content = @Content(schema = @Schema(implementation = Policy.class)) + ), @ApiResponse(responseCode = "304", description = "The policy already has the specified project assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The policy or project could not be found") @@ -265,7 +282,11 @@ public Response addProjectToPolicy( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204", content = @Content(schema = @Schema(implementation = Policy.class))), + @ApiResponse( + responseCode = "200", + description = "The updated policy", + content = @Content(schema = @Schema(implementation = Policy.class)) + ), @ApiResponse(responseCode = "304", description = "The policy does not have the specified project assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The policy or project could not be found") @@ -304,7 +325,11 @@ public Response removeProjectFromPolicy( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Policy.class))), + @ApiResponse( + responseCode = "200", + description = "The updated policy", + content = @Content(schema = @Schema(implementation = Policy.class)) + ), @ApiResponse(responseCode = "304", description = "The policy already has the specified tag assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The policy or tag could not be found") @@ -344,7 +369,11 @@ public Response addTagToPolicy( description = "

Requires permission POLICY_MANAGEMENT or POLICY_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204", content = @Content(schema = @Schema(implementation = Policy.class))), + @ApiResponse( + responseCode = "200", + description = "The updated policy", + content = @Content(schema = @Schema(implementation = Policy.class)) + ), @ApiResponse(responseCode = "304", description = "The policy does not have the specified tag assigned"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "404", description = "The policy or tag could not be found") diff --git a/src/main/java/org/dependencytrack/resources/v1/PolicyViolationResource.java b/src/main/java/org/dependencytrack/resources/v1/PolicyViolationResource.java index daaf323d1..6de803382 100644 --- a/src/main/java/org/dependencytrack/resources/v1/PolicyViolationResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/PolicyViolationResource.java @@ -75,6 +75,7 @@ public class PolicyViolationResource extends AlpineResource { @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all policy violations for the entire portfolio", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of policy violations", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = PolicyViolation.class))) ), @@ -102,6 +103,7 @@ public Response getViolations(@Parameter(description = "Optionally includes supp @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all policy violations for a specific project", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of policy violations", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = PolicyViolation.class))) ), @@ -142,6 +144,7 @@ public Response getViolationsByProject(@Parameter(description = "The UUID of the @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all policy violations for a specific component", headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of policy violations", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = PolicyViolation.class))) ), diff --git a/src/main/java/org/dependencytrack/resources/v1/ProjectPropertyResource.java b/src/main/java/org/dependencytrack/resources/v1/ProjectPropertyResource.java index 487d07ec2..8cec57331 100644 --- a/src/main/java/org/dependencytrack/resources/v1/ProjectPropertyResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/ProjectPropertyResource.java @@ -70,7 +70,11 @@ public class ProjectPropertyResource extends AbstractConfigPropertyResource { description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_READ

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ProjectProperty.class)))), + @ApiResponse( + responseCode = "200", + description = "A list of all ProjectProperties for the specified project", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = ProjectProperty.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") @@ -112,7 +116,11 @@ public Response getProperties( description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = ProjectProperty.class))), + @ApiResponse( + responseCode = "201", + description = "The created project property", + content = @Content(schema = @Schema(implementation = ProjectProperty.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"), @@ -168,7 +176,11 @@ public Response createProperty( description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_UPDATE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = ProjectProperty.class))), + @ApiResponse( + responseCode = "200", + description = "The updated project property", + content = @Content(schema = @Schema(implementation = ProjectProperty.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"), @@ -211,7 +223,7 @@ public Response updateProperty( description = "

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_DELETE

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "204"), + @ApiResponse(responseCode = "204", description = "Project property removed successfully"), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "403", description = "Access to the specified project is forbidden"), @ApiResponse(responseCode = "404", description = "The project or project property could not be found"), diff --git a/src/main/java/org/dependencytrack/resources/v1/ProjectResource.java b/src/main/java/org/dependencytrack/resources/v1/ProjectResource.java index b968e8b0a..8f69556bc 100644 --- a/src/main/java/org/dependencytrack/resources/v1/ProjectResource.java +++ b/src/main/java/org/dependencytrack/resources/v1/ProjectResource.java @@ -62,6 +62,7 @@ import org.dependencytrack.persistence.jdbi.ProjectDao; import org.dependencytrack.persistence.jdbi.ProjectDao.ConciseProjectListRow; import org.dependencytrack.resources.v1.openapi.PaginatedApi; +import org.dependencytrack.resources.v1.vo.BomUploadResponse; import org.dependencytrack.resources.v1.vo.CloneProjectRequest; import org.dependencytrack.resources.v1.vo.ConciseProject; @@ -103,7 +104,9 @@ public class ProjectResource extends AlpineResource { ) @PaginatedApi @ApiResponses(value = { - @ApiResponse(responseCode = "200", + @ApiResponse( + responseCode = "200", + description = "A list of all projects", headers = @Header(name = TOTAL_COUNT_HEADER, schema = @Schema(format = "integer"), description = "The total number of projects"), content = @Content(array = @ArraySchema(schema = @Schema(implementation = Project.class))) ), @@ -141,7 +144,9 @@ public Response getProjects(@Parameter(description = "The optional name of the p ) @PaginatedApi @ApiResponses(value = { - @ApiResponse(responseCode = "200", + @ApiResponse( + responseCode = "200", + description = "A list of all projects in concise representation", headers = @Header(name = TOTAL_COUNT_HEADER, schema = @Schema(format = "integer"), description = "The total number of projects"), content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConciseProject.class))) ), @@ -179,7 +184,10 @@ public Response getProjectsConcise( ) @PaginatedApi @ApiResponses(value = { - @ApiResponse(headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of child projects", schema = @Schema(format = "integer")), + @ApiResponse( + responseCode = "200", + description = "A list of all child projects in a concise representation", + headers = @Header(name = TOTAL_COUNT_HEADER, description = "The total number of child projects", schema = @Schema(format = "integer")), content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConciseProject.class))) ), @ApiResponse(responseCode = "401", description = "Unauthorized") @@ -215,7 +223,11 @@ public Response getProjectChildrenConcise( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Project.class))), + @ApiResponse( + responseCode = "200", + description = "A specific project", + content = @Content(schema = @Schema(implementation = Project.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") @@ -248,7 +260,11 @@ public Response getProject( description = "

Requires permission VIEW_PORTFOLIO

" ) @ApiResponses(value = { - @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Project.class))), + @ApiResponse( + responseCode = "200", + description = "A specific project by its name and version", + content = @Content(schema = @Schema(implementation = Project.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") @@ -284,6 +300,7 @@ public Response getProject( @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all projects by tag", 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))) ), @@ -315,6 +332,7 @@ public Response getProjectsByTag( @ApiResponses(value = { @ApiResponse( responseCode = "200", + description = "A list of all projects by classifier", 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))) ), @@ -347,7 +365,11 @@ public Response getProjectsByClassifier(

Requires permission PORTFOLIO_MANAGEMENT or PORTFOLIO_MANAGEMENT_CREATE

""" ) @ApiResponses(value = { - @ApiResponse(responseCode = "201", content = @Content(schema = @Schema(implementation = Project.class))), + @ApiResponse( + responseCode = "201", + description = "The created project", + content = @Content(schema = @Schema(implementation = Project.class)) + ), @ApiResponse(responseCode = "401", description = "Unauthorized"), @ApiResponse(responseCode = "409", description = """