Add swagger docs

Author: EvalVis

pom.xml

@@ -11,7 +11,7 @@
     <parent>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-parent</artifactId>
-        <version>3.3.3</version>
+        <version>3.5.0</version>
         <relativePath/>
     </parent>
 
@@ -31,6 +31,11 @@
             <version>5.11.3</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.8.8</version>
+        </dependency>
     </dependencies>
 
     <build>

src/main/java/com/programmersdiary/CenterTakingRequest.java

@@ -1,4 +1,16 @@
 package com.programmersdiary;
 
-public record CenterTakingRequest(Tile tileToTake, int tilesToPutOnFloor, int patternLineIndex) {
-}
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "Request to take tiles from the center area")
+public record CenterTakingRequest(
+    @Schema(description = "Tile color to take from center", example = "BLUE", 
+            allowableValues = {"RED", "BLUE", "YELLOW", "BLACK", "WHITE"})
+    Tile tileToTake, 
+    
+    @Schema(description = "Number of tiles to put on floor", example = "1", minimum = "0")
+    int tilesToPutOnFloor, 
+    
+    @Schema(description = "Pattern line index (0-4) where remaining tiles go", example = "2", minimum = "0", maximum = "4")
+    int patternLineIndex
+) {}

src/main/java/com/programmersdiary/FactoryTakingRequest.java

@@ -1,4 +1,19 @@
 package com.programmersdiary;
 
-public record FactoryTakingRequest(int factoryIndex, Tile tileToTake, int tilesToPutOnFloor, int patternLineIndex) {
-}
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "Request to take tiles from a factory display")
+public record FactoryTakingRequest(
+    @Schema(description = "Factory display index (0-4)", example = "0", minimum = "0", maximum = "4")
+    int factoryIndex, 
+    
+    @Schema(description = "Tile color to take", example = "RED", 
+            allowableValues = {"RED", "BLUE", "YELLOW", "BLACK", "WHITE"})
+    Tile tileToTake, 
+    
+    @Schema(description = "Number of tiles to put on floor", example = "0", minimum = "0")
+    int tilesToPutOnFloor, 
+    
+    @Schema(description = "Pattern line index (0-4) where remaining tiles go", example = "1", minimum = "0", maximum = "4")
+    int patternLineIndex
+) {}

src/main/java/com/programmersdiary/GameController.java

@@ -1,5 +1,10 @@
 package com.programmersdiary;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -8,6 +13,7 @@
 import java.util.Map;
 
 @RestController
+@Tag(name = "Azul Game", description = "An API for Azul board game")
 public class GameController {
     private final Game game;
 
@@ -16,16 +22,34 @@ public GameController(Game game) {
     }
 
     @GetMapping("/show")
+    @Operation(summary = "Get game state as a plain-text", description = "Returns the current game state as a plain-text")
+    @ApiResponse(responseCode = "200", description = "Current game state")
     public String show() {
         return game.toString();
     }
 
     @GetMapping("/showJson")
+    @Operation(summary = "Get game state as JSON", description = "Returns the current game state as a JSON object")
+    @ApiResponse(responseCode = "200", description = "Current game state in JSON format")
     public Map<String, Object> showJson() {
         return game.jsonObject();
     }
 
     @PostMapping("/takeFromFactory")
+    @Operation(summary = "Take tiles from factory", 
+               description = "Take tiles of a specific color from a factory display, drop some on the floor (if you want) and put them on a pattern line")
+    @ApiResponse(responseCode = "200", description = "Updated game state after taking tiles")
+    @io.swagger.v3.oas.annotations.parameters.RequestBody(
+        content = @Content(
+            examples = {
+                @ExampleObject(
+                    name = "Take RED tiles",
+                    description = "The example is not guaranteed to work due to randomness of game. Please check the board state first!",
+                    value = "{\"factoryIndex\": 0, \"tileToTake\": \"RED\", \"tilesToPutOnFloor\": 0, \"patternLineIndex\": 1}"
+                )
+            }
+        )
+    )
     public Map<String, Object> takeTilesFromFactory(@RequestBody FactoryTakingRequest factoryTakingRequest) {
         game.executeFactoryOfferPhaseWithFactory(
                 factoryTakingRequest.factoryIndex(), factoryTakingRequest.tileToTake(),
@@ -35,6 +59,20 @@ public Map<String, Object> takeTilesFromFactory(@RequestBody FactoryTakingReques
     }
 
     @PostMapping("/takeFromCenter")
+    @Operation(summary = "Take tiles from center", 
+               description = "Take tiles of a specific color from the center area, drop some on the floor (if you want) and put them on a pattern line")
+    @ApiResponse(responseCode = "200", description = "Updated game state after taking tiles")
+    @io.swagger.v3.oas.annotations.parameters.RequestBody(
+        content = @Content(
+            examples = {
+                @ExampleObject(
+                    name = "Take BLUE tiles",
+                    description = "The example is not guaranteed to work due to randomness of game. Please check the board state first!",
+                    value = "{\"tileToTake\": \"BLUE\", \"tilesToPutOnFloor\": 1, \"patternLineIndex\": 2}"
+                )
+            }
+        )
+    )
     public Map<String, Object> takeTilesFromCenter(@RequestBody CenterTakingRequest centerTakingRequest) {
         game.executeFactoryOfferPhaseWithCenter(
                 centerTakingRequest.tileToTake(), centerTakingRequest.tilesToPutOnFloor(),