docs(openapi): add docs for attachment

Added OpenAPI docs using springdoc for: - `/attachments` - `/changelog` - `/clearingrequest` Signed-off-by: Gaurav Mishra <gmishx@gmail.com>
eclipse-sw360 · Aug 25, 2023 · 1a534db · 1a534db
1 parent f9ef5c1
commit 1a534db
Show file tree

Hide file tree

Showing 4 changed files with 118 additions and 19 deletions.
diff --git a/.../src/main/java/org/eclipse/sw360/rest/resourceserver/attachment/AttachmentController.java b/.../src/main/java/org/eclipse/sw360/rest/resourceserver/attachment/AttachmentController.java
@@ -10,6 +10,10 @@
 
 package org.eclipse.sw360.rest.resourceserver.attachment;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -31,7 +35,10 @@
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.rest.webmvc.BasePathAwareController;
 import org.springframework.data.rest.webmvc.RepositoryLinksResource;
-import org.springframework.hateoas.*;
+import org.springframework.hateoas.CollectionModel;
+import org.springframework.hateoas.EntityModel;
+import org.springframework.hateoas.Link;
+import org.springframework.hateoas.UriTemplate;
 import org.springframework.hateoas.server.RepresentationModelProcessor;
 import org.springframework.hateoas.server.mvc.WebMvcLinkBuilder;
 import org.springframework.http.HttpStatus;
@@ -49,6 +56,8 @@
 @BasePathAwareController
 @Slf4j
 @RequiredArgsConstructor(onConstructor = @__(@Autowired))
+@RestController
+@SecurityRequirement(name = "tokenAuth")
 public class AttachmentController implements RepresentationModelProcessor<RepositoryLinksResource> {
     public static final String ATTACHMENTS_URL = "/attachments";
 
@@ -67,18 +76,33 @@ public class AttachmentController implements RepresentationModelProcessor<Reposi
     @NonNull
     private final RestControllerHelper restControllerHelper;
 
+    @Operation(
+            summary = "Get attachment information.",
+            description = "Get attachment information.",
+            tags = {"Attachments"}
+    )
     @GetMapping(value = ATTACHMENTS_URL + "/{id}")
     public ResponseEntity<EntityModel<Attachment>> getAttachmentForId(
-            @PathVariable("id") String id) throws TException {
+            @Parameter(description = "id of the attachment")
+            @PathVariable("id") String id
+    ) throws TException {
 
         User sw360User = restControllerHelper.getSw360UserFromAuthentication();
         AttachmentInfo attachmentInfo = attachmentService.getAttachmentById(id);
         HalResource<Attachment> attachmentResource = createHalAttachment(attachmentInfo, sw360User);
         return new ResponseEntity<>(attachmentResource, HttpStatus.OK);
     }
 
+    @Operation(
+            summary = "Get attachment information by sha1.",
+            description = "Get attachment information by sha1 and the resource having it.",
+            tags = {"Attachments"}
+    )
     @GetMapping(value = ATTACHMENTS_URL)
-    public ResponseEntity<CollectionModel<EntityModel<Attachment>>> getAttachments(@RequestParam String sha1) throws TException {
+    public ResponseEntity<CollectionModel<EntityModel<Attachment>>> getAttachments(
+            @Parameter(description = "sha1 of the attachment", required = true)
+            @RequestParam String sha1
+    ) throws TException {
         User sw360User = restControllerHelper.getSw360UserFromAuthentication();
         List<AttachmentInfo> attachmentInfos = attachmentService.getAttachmentsBySha1(sha1);
 
@@ -96,8 +120,22 @@ public ResponseEntity<CollectionModel<EntityModel<Attachment>>> getAttachments(@
         }
     }
 
+    @Operation(
+            summary = "Create attachment.",
+            description = "Create an attachment.",
+            tags = {"Attachments"}
+    )
     @RequestMapping(value = ATTACHMENTS_URL , method = RequestMethod.POST, consumes = {MediaType.MULTIPART_MIXED_VALUE, MediaType.MULTIPART_FORM_DATA_VALUE})
-    public ResponseEntity<List<AttachmentDTO>> createAttachment(@RequestParam ("files") List<MultipartFile> files) throws TException, IOException {
+    public ResponseEntity<List<AttachmentDTO>> createAttachment(
+            @Parameter(description = "List of files to attach",
+                    schema = @Schema(
+                            type = "string",
+                            format = "binary",
+                            description = "File to attach"
+                    )
+            )
+            @RequestParam("files") List<MultipartFile> files
+    ) throws TException, IOException {
         if (files == null || files.isEmpty()) {
             throw new RuntimeException("You must select at least one file for uploading");
         }

diff --git a/...er/src/main/java/org/eclipse/sw360/rest/resourceserver/changelog/ChangeLogController.java b/...er/src/main/java/org/eclipse/sw360/rest/resourceserver/changelog/ChangeLogController.java
@@ -20,6 +20,12 @@
 
 import javax.servlet.http.HttpServletRequest;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import org.apache.thrift.TException;
@@ -30,13 +36,13 @@
 import org.eclipse.sw360.datahandler.resourcelists.ResourceClassNotFoundException;
 import org.eclipse.sw360.datahandler.thrift.changelogs.ChangeLogs;
 import org.eclipse.sw360.datahandler.thrift.users.User;
-import org.eclipse.sw360.rest.resourceserver.attachment.AttachmentController;
 import org.eclipse.sw360.rest.resourceserver.core.RestControllerHelper;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.rest.webmvc.BasePathAwareController;
 import org.springframework.data.rest.webmvc.RepositoryLinksResource;
 import org.springframework.hateoas.Link;
+import org.springframework.hateoas.MediaTypes;
 import org.springframework.hateoas.server.RepresentationModelProcessor;
 import org.springframework.hateoas.CollectionModel;
 import org.springframework.hateoas.UriTemplate;
@@ -54,9 +60,12 @@
 
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.RestController;
 
 @BasePathAwareController
 @RequiredArgsConstructor(onConstructor = @__(@Autowired))
+@RestController
+@SecurityRequirement(name = "tokenAuth")
 public class ChangeLogController implements RepresentationModelProcessor<RepositoryLinksResource> {
 
     private static final Logger log = LogManager.getLogger(ChangeLogController.class);
@@ -71,9 +80,27 @@ public class ChangeLogController implements RepresentationModelProcessor<Reposit
     @NonNull
     private final com.fasterxml.jackson.databind.Module sw360Module;
 
+    @Operation(
+            summary = "Get change logs for a document.",
+            description = "List all the changelog based on the document id and parent document id.",
+            tags = {"Changelog"},
+            responses = {
+                    @ApiResponse(
+                            responseCode = "200",
+                            content = {
+                                    @Content(mediaType = MediaTypes.HAL_JSON_VALUE,
+                                            schema = @Schema(implementation = ChangeLogs.class))
+                            }
+                    ),
+            }
+    )
     @RequestMapping(value = CHANGE_LOG_URL + "/document/{id}", method = RequestMethod.GET)
-    public ResponseEntity getChangeLogForDocument(Pageable pageable, @PathVariable("id") String docId,
-            HttpServletRequest request) throws TException, URISyntaxException, PaginationParameterException,
+    public ResponseEntity getChangeLogForDocument(
+            Pageable pageable,
+            @Parameter(description = "id of the document")
+            @PathVariable("id") String docId,
+            HttpServletRequest request
+    ) throws TException, URISyntaxException, PaginationParameterException,
             ResourceClassNotFoundException {
         User sw360User = restControllerHelper.getSw360UserFromAuthentication();
         List<ChangeLogs> changelogs = sw360ChangeLogService.getChangeLogsByDocumentId(docId, sw360User);

diff --git a/...java/org/eclipse/sw360/rest/resourceserver/clearingrequest/ClearingRequestController.java b/...java/org/eclipse/sw360/rest/resourceserver/clearingrequest/ClearingRequestController.java
@@ -20,6 +20,10 @@
 
 import javax.servlet.http.HttpServletRequest;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import org.apache.thrift.TException;
 import org.eclipse.sw360.datahandler.thrift.ClearingRequestState;
 import org.eclipse.sw360.datahandler.thrift.projects.ClearingRequest;
@@ -38,17 +42,16 @@
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.util.StringUtils;
-import org.springframework.web.bind.annotation.PathVariable;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RequestMethod;
-import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.*;
 import org.springframework.web.server.ResponseStatusException;
 
 import lombok.NonNull;
 import lombok.RequiredArgsConstructor;
 
 @BasePathAwareController
 @RequiredArgsConstructor(onConstructor = @__(@Autowired))
+@RestController
+@SecurityRequirement(name = "tokenAuth")
 public class ClearingRequestController implements RepresentationModelProcessor<RepositoryLinksResource> {
 
     public static final String CLEARING_REQUEST_URL = "/clearingrequest";
@@ -68,19 +71,37 @@ public class ClearingRequestController implements RepresentationModelProcessor<R
     private final com.fasterxml.jackson.databind.Module sw360Module;
 
 
+    @Operation(
+            summary = "Get clearing request by id.",
+            description = "Get a clearing request by id.",
+            tags = {"ClearingRequest"}
+    )
     @RequestMapping(value = CLEARING_REQUEST_URL + "/{id}", method = RequestMethod.GET)
-    public ResponseEntity<EntityModel<ClearingRequest>> getClearingRequestById(Pageable pageable, @PathVariable("id") String docId,
-            HttpServletRequest request) throws TException, URISyntaxException {
+    public ResponseEntity<EntityModel<ClearingRequest>> getClearingRequestById(
+            Pageable pageable,
+            @Parameter(description = "id of the clearing request")
+            @PathVariable("id") String docId,
+            HttpServletRequest request
+    ) throws TException, URISyntaxException {
         User sw360User = restControllerHelper.getSw360UserFromAuthentication();
         ClearingRequest clearingRequest = sw360ClearingRequestService.getClearingRequestById(docId, sw360User);
         HalResource<ClearingRequest> halClearingRequest = createHalClearingRequestWithAllDetails(clearingRequest, sw360User);
         HttpStatus status = halClearingRequest == null ? HttpStatus.NO_CONTENT : HttpStatus.OK;
         return new ResponseEntity<>(halClearingRequest, status);
     }
 
+    @Operation(
+            summary = "Get the ClearingRequest based on the project id.",
+            description = "Get the ClearingRequest based on the project id.",
+            tags = {"ClearingRequest"}
+    )
     @RequestMapping(value = CLEARING_REQUEST_URL + "/project/{id}", method = RequestMethod.GET)
-    public ResponseEntity<EntityModel<ClearingRequest>> getClearingRequestByProjectId(Pageable pageable, @PathVariable("id") String projectId,
-            HttpServletRequest request) throws TException, URISyntaxException {
+    public ResponseEntity<EntityModel<ClearingRequest>> getClearingRequestByProjectId(
+            Pageable pageable,
+            @Parameter(description = "id of the project")
+            @PathVariable("id") String projectId,
+            HttpServletRequest request
+    ) throws TException, URISyntaxException {
         User sw360User = restControllerHelper.getSw360UserFromAuthentication();
         ClearingRequest clearingRequest = sw360ClearingRequestService.getClearingRequestByProjectId(projectId, sw360User);
         HalResource<ClearingRequest> halClearingRequest = createHalClearingRequestWithAllDetails(clearingRequest, sw360User);
@@ -102,9 +123,22 @@ private HalResource<ClearingRequest> createHalClearingRequestWithAllDetails(Clea
         return halClearingRequest;
     }
 
+    @Operation(
+            summary = "Get all the Clearing Requests visible to the user.",
+            description = "Get all the Clearing Requests visible to the user.",
+            tags = {"ClearingRequest"}
+    )
     @RequestMapping(value = CLEARING_REQUESTS_URL, method = RequestMethod.GET)
-    public ResponseEntity<CollectionModel<EntityModel<ClearingRequest>>> getMyClearingRequests(Pageable pageable,
-            @RequestParam(value = "state", required = false) String state, HttpServletRequest request) throws TException {
+    public ResponseEntity<CollectionModel<EntityModel<ClearingRequest>>> getMyClearingRequests(
+            Pageable pageable,
+            @Parameter(description = "The clearing request state of the request.",
+                    schema = @Schema(
+                            implementation = ClearingRequestState.class
+                    )
+            )
+            @RequestParam(value = "state", required = false) String state,
+            HttpServletRequest request
+    ) throws TException {
 
         User sw360User = restControllerHelper.getSw360UserFromAuthentication();
         Set<ClearingRequest> clearingRequestSet = new TreeSet<>();

diff --git a/...erver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/JacksonCustomizations.java b/...erver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/JacksonCustomizations.java
@@ -742,7 +742,7 @@ static abstract class ClearingReportMixin {
                 "setSuperAttachmentId",
                 "setSuperAttachmentFilename"
         })
-        static abstract class AttachmentMixin {
+        static abstract class AttachmentMixin extends Attachment {
         }
 
         @JsonInclude(JsonInclude.Include.NON_NULL)
@@ -767,7 +767,7 @@ static abstract class AttachmentMixin {
                 "setSuperAttachmentFilename",
                 "setUsageAttachment"
         })
-        static abstract class AttachmentDTOMixin {
+        static abstract class AttachmentDTOMixin extends AttachmentDTO {
         }
 
         @JsonInclude(JsonInclude.Include.NON_NULL)