adding more swagger docs (#80)

Author: hospel

src/main/java/com/answerdigital/answerking/config/SwaggerConfig.java

@@ -30,10 +30,11 @@ public GroupedOpenApi actuatorApi() {
     @Bean
     public OpenAPI springShopOpenAPI() {
         return new OpenAPI()
-                .info(new Info().title("AnswerKing API")
-                        .description("Answer King application")
-                        .version("v0.0.1")
-                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));
+                .info(new Info()
+                         .title("AnswerKing API")
+                         .description("Answer King application")
+                         .version("v1")
+                         .license(new License().name("Apache 2.0").url("http://springdoc.org")));
     }
 
 }

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

@@ -1,5 +1,6 @@
 package com.answerdigital.answerking.controller;
 
+import com.answerdigital.answerking.exception.util.ErrorResponse;
 import com.answerdigital.answerking.model.Category;
 import com.answerdigital.answerking.request.AddCategoryRequest;
 import com.answerdigital.answerking.request.UpdateCategoryRequest;
@@ -41,16 +42,23 @@ public CategoryController(final CategoryService categoryService) {
         this.categoryService = categoryService;
     }
 
+    @Operation(summary = "Create a new category")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "201", description = "When the category has been created.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Category.class)) }),
+        @ApiResponse(responseCode = "400", description = "When invalid parameters are provided.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @PostMapping
     public ResponseEntity<Category> addCategory(@Valid @RequestBody final AddCategoryRequest categoryRequest,
                                                 final Errors errors) {
         return new ResponseEntity<>(categoryService.addCategory(categoryRequest),
                                                         errors.hasErrors() ? HttpStatus.BAD_REQUEST : HttpStatus.CREATED);
     }
 
-    @Operation(summary = "Get all categories.")
+    @Operation(summary = "Get all categories")
     @ApiResponses(value = {
-        @ApiResponse(responseCode = "200", description = "Found the the list of categories",
+        @ApiResponse(responseCode = "200", description = "Found the list of categories",
             content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Category.class)) })
     })
     @GetMapping
@@ -59,23 +67,49 @@ public ResponseEntity<Collection<Category>> getAllCategories() {
         return new ResponseEntity<>(categories, categories.isEmpty() ? HttpStatus.NO_CONTENT : HttpStatus.OK);
     }
 
+    @Operation(summary = "Get a single category")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "When the category with the provided id has been found.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Category.class)) }),
+        @ApiResponse(responseCode = "404", description = "When the category with the given id does not exist",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @GetMapping("/{categoryId}")
     public ResponseEntity<Category> getCategoryById(@PathVariable @NotNull final Long categoryId) {
         return new ResponseEntity<>(categoryService.findById(categoryId), HttpStatus.OK);
     }
 
+    @Operation(summary = "Add product to a category")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "Add product to a category.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Category.class)) })
+    })
     @PutMapping("/{categoryId}/addproduct/{productId}")
     public ResponseEntity<Category> addProductToCategory(@PathVariable @NotNull final Long categoryId,
                                                          @PathVariable @NotNull final Long productId) {
         return new ResponseEntity<>(categoryService.addProductToCategory(categoryId, productId), HttpStatus.OK);
     }
 
+    @Operation(summary = "Remove product from a category")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "Remove product from a category.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Category.class)) })
+    })
     @PutMapping("/{categoryId}/removeproduct/{productId}")
     public ResponseEntity<Category> removeProductFromCategory(@PathVariable @NotNull final Long categoryId,
                                                               @PathVariable @NotNull final Long productId) {
         return new ResponseEntity<>(categoryService.removeProductFromCategory(categoryId, productId), HttpStatus.OK);
     }
 
+    @Operation(summary = "Update an existing category.")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "When the category has been updated.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Category.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 category with the given id does not exist.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @PutMapping("/{categoryId}")
     public ResponseEntity<Category> updateCategory(@Valid @RequestBody final UpdateCategoryRequest updateCategoryRequest,
                                                    @PathVariable @NotNull final Long categoryId,
@@ -84,6 +118,17 @@ public ResponseEntity<Category> updateCategory(@Valid @RequestBody final UpdateC
                                                     errors.hasErrors() ? HttpStatus.BAD_REQUEST : HttpStatus.OK);
     }
 
+    @Operation(summary = "Retire an existing category.")
+    @ApiResponses(value = {
+        @ApiResponse(responseCode = "200", description = "When the category has been retired.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = Category.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 category with the given id does not exist.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) }),
+        @ApiResponse(responseCode = "410", description = "When the category with the given id is already retired.",
+                content = { @Content(mediaType = "application/json", schema = @Schema(implementation = ErrorResponse.class)) })
+    })
     @DeleteMapping("/{categoryId}")
     public ResponseEntity<Category> retireCategory(@PathVariable @NotNull final Long categoryId) {
         return new ResponseEntity<>(categoryService.retireCategory(categoryId), HttpStatus.OK);