M2 certificate response entity

application/module-certificate/src/main/java/org/fuseri/modulecertificate/service/CertificateController.java

 package org.fuseri.modulecertificate.service;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import jakarta.persistence.EntityNotFoundException;
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotNull;
 import org.fuseri.model.dto.certificate.CertificateCreateDto;
-import org.fuseri.model.dto.certificate.CertificateDto;
 import org.fuseri.model.dto.certificate.CertificateSimpleDto;
-import org.fuseri.model.dto.common.Result;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
+import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
+import org.springframework.http.HttpStatus;
 
 import java.util.List;
 
@@ -35,9 +40,16 @@ public class CertificateController {
      * @param certificateCreateDto Dto with data used for generating certificate
      * @return CertificateDto with data of generated certificate
      */
-    @PostMapping("/generate")
-    public CertificateSimpleDto generate(@Valid @RequestBody CertificateCreateDto certificateCreateDto) {
-        return certificateFacade.generate(certificateCreateDto);
+    @Operation(summary = "Generate certificate",
+            description = "Generates certificate, saves it into database and returns certificate information and certificate file.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "201", description = "Certificate generated successfully."),
+            @ApiResponse(responseCode = "400", description = "Invalid input.")
+    })
+    @PostMapping
+    public ResponseEntity<CertificateSimpleDto> generate(@Valid @RequestBody CertificateCreateDto certificateCreateDto) {
+        var certificateSimpleDto = certificateFacade.generate(certificateCreateDto);
+        return ResponseEntity.status(HttpStatus.CREATED).body(certificateSimpleDto);
     }
 
     /**
@@ -46,9 +58,18 @@ public class CertificateController {
      * @param id ID of certificate to be retrieved
      * @return CertificateDto with data of previously generated certificate with specified ID
      */
-    @GetMapping("/find")
-    public CertificateSimpleDto find(@RequestParam Long id) {
-        return certificateFacade.findById(id);
+    @Operation(summary = "Get a certificate by ID", description = "Returns a certificate with the specified ID.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Certificate with the specified ID retrieved successfully."),
+            @ApiResponse(responseCode = "404", description = "Certificate with the specified ID was not found.")
+    })
+    @GetMapping("/{id}")
+    public ResponseEntity<CertificateSimpleDto> find(@NotNull @PathVariable  Long id) {
+        try {
+            return ResponseEntity.ok(certificateFacade.findById(id));
+        } catch (EntityNotFoundException e) {
+            return ResponseEntity.notFound().build();
+        }
     }
 
     /**
@@ -58,9 +79,14 @@ public class CertificateController {
      * @return List of CertificateDto objects with previously generated certificates
      * for specified User.
      */
+    @Operation(summary = "Get certificates for user", description = "Returns certificates for given user in list.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Successfully retrieved certificates"),
+            @ApiResponse(responseCode = "400", description = "Invalid input."),
+    })
     @GetMapping("/findForUser")
-    public List<CertificateSimpleDto> findForUser(@RequestParam Long userId) {
-        return certificateFacade.findByUserId(userId);
+    public ResponseEntity<List<CertificateSimpleDto>> findForUser(@RequestParam Long userId) {
+        return ResponseEntity.ok(certificateFacade.findByUserId(userId));
     }
 
     /**
@@ -71,9 +97,15 @@ public class CertificateController {
      * @return List of CertificateDto objects with previously generated certificates
      * for specified User and Course.
      */
+    @Operation(summary = "Get certificates for user and course",
+            description = "Returns certificates for given user and course in list.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Successfully retrieved certificates"),
+            @ApiResponse(responseCode = "400", description = "Invalid input."),
+    })
     @GetMapping("/findForUserAndCourse")
-    public List<CertificateSimpleDto> findForUserAndCourse(@RequestParam Long userId, @RequestParam Long courseId) {
-        return certificateFacade.findByUserIdAndCourseId(userId, courseId);
+    public ResponseEntity<List<CertificateSimpleDto>> findForUserAndCourse(@RequestParam Long userId, @RequestParam Long courseId) {
+        return  ResponseEntity.ok(certificateFacade.findByUserIdAndCourseId(userId, courseId));
     }
 
     /**
@@ -81,9 +113,14 @@ public class CertificateController {
      *
      * @param id Id of certificate to be deleted.
      */
-    @DeleteMapping("/delete")
-    public void delete(@RequestParam Long id) {
+    @Operation(summary = "Delete a certificate with specified ID", description = "Deletes a certificate with the specified ID.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "204", description = "Certificate with the specified ID deleted successfully."),
+    })
+    @DeleteMapping("/{id}")
+    public ResponseEntity<Void> delete(@NotNull @PathVariable Long id) {
         certificateFacade.deleteCertificate(id);
+        return ResponseEntity.noContent().build();
     }
 
     /**
@@ -91,8 +128,13 @@ public class CertificateController {
      *
      * @return a Result object containing a list of CertificateDto objects and pagination information
      */
-    @GetMapping("/findAll")
-    public Page<CertificateSimpleDto> findAllCertificates(Pageable pageable) {
-        return certificateFacade.findAll(pageable);
+    @Operation(summary = "Get certificates in paginated format", description = "Returns certificates in paginated format.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Successfully retrieved paginated certificates"),
+            @ApiResponse(responseCode = "400", description = "Invalid page number supplied"),
+    })
+    @GetMapping
+    public ResponseEntity<Page<CertificateSimpleDto>> findAllCertificates(Pageable pageable) {
+        return ResponseEntity.ok(certificateFacade.findAll(pageable));
     }
 }