Defined API responses for product HTTP requests

Author: MohammadIqbalAD

src/main/java/com/answerdigital/answerking/controller/ProductController.java

@@ -1,8 +1,14 @@
 package com.answerdigital.answerking.controller;
 
+import com.answerdigital.answerking.exception.util.ErrorResponse;
 import com.answerdigital.answerking.model.Product;
 import com.answerdigital.answerking.request.ProductRequest;
 import com.answerdigital.answerking.service.ProductService;
+import io.swagger.v3.oas.annotations.Operation;
+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.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
@@ -34,23 +40,51 @@ public ProductController(final ProductService productService) {
         this.productService = productService;
     }
 
+    @Operation(summary = "Get all products.")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "When all the products have been returned.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class)) })
+    })
     @GetMapping
     public ResponseEntity<List<Product>> getAllProducts() {
         final List<Product> products = productService.findAll();
         return new ResponseEntity<>(products, products.isEmpty() ? HttpStatus.NO_CONTENT : HttpStatus.OK);
     }
 
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "When the product with the provided id has been found.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class)) }),
+        @ApiResponse(responseCode = "404", description = "When the product with the given id does not exist.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @GetMapping(path = "/{id}")
-    public ResponseEntity<Product> getProductById(@Valid @PathVariable @NotNull final Long id) {
-        return new ResponseEntity<>(productService.findById(id), HttpStatus.OK);
+    public ResponseEntity<Product> getProductById(@Valid @PathVariable @NotNull final Long id, final Errors errors) {
+        return new ResponseEntity<>(productService.findById(id),
+                                            errors.hasErrors() ? HttpStatus.NOT_FOUND : HttpStatus.OK);
     }
 
+    @Operation(summary = "Create a new product.")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "201", description = "When the product has been created.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class)) }),
+        @ApiResponse(responseCode = "400", description = "When invalid parameters are provided.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @PostMapping
     public ResponseEntity<Product> addProduct(@Valid @RequestBody final ProductRequest productRequest, final Errors errors) {
         return new ResponseEntity<>(productService.addNewProduct(productRequest),
                                             errors.hasErrors() ? HttpStatus.BAD_REQUEST : HttpStatus.CREATED);
     }
 
+    @Operation(summary = "Update an existing product.")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "When the product has been updated.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class)) }),
+        @ApiResponse(responseCode = "400", description = "When invalid parameters are provided.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) }),
+        @ApiResponse(responseCode = "404", description = "When the product with the given id does not exist.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @PutMapping("/{id}")
     public ResponseEntity<Product> updateProduct(@PathVariable @NotNull final Long id,
                                               @Valid @RequestBody final ProductRequest productRequest,
@@ -59,6 +93,15 @@ public ResponseEntity<Product> updateProduct(@PathVariable @NotNull final Long i
                                             errors.hasErrors() ? HttpStatus.BAD_REQUEST : HttpStatus.OK);
     }
 
+    @Operation(summary = "Retire an existing product.")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "When the product has been retired.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Product.class)) }),
+        @ApiResponse(responseCode = "404", description = "When the product with the given id does not exist.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) }),
+        @ApiResponse(responseCode = "410", description = "When the product with the given id is already retired.",
+            content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @DeleteMapping("/{id}")
     public ResponseEntity<Product> retireProduct(@PathVariable @NotNull final Long id) {
         return new ResponseEntity<>(productService.retireProduct(id), HttpStatus.OK);

src/main/java/com/answerdigital/answerking/model/Product.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
 import lombok.Builder;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -37,6 +38,7 @@
 public class Product {
     @Id
     @GeneratedValue(strategy = GenerationType.IDENTITY)
+    @JsonProperty(access = JsonProperty.Access.READ_ONLY)
     private Long id;
 
     private String name;
@@ -46,6 +48,7 @@ public class Product {
     @Column(precision = 12, scale = 2)
     private BigDecimal price;
 
+    @JsonProperty(access = JsonProperty.Access.READ_ONLY)
     private boolean retired;
 
     @JsonIgnore