Documented Rooms

api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomInfoResponse.java

@@ -1,5 +1,7 @@
 package ru.dragonestia.picker.api.repository.response;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import ru.dragonestia.picker.api.repository.response.type.RRoom;
 
+@Schema(title = "Room info", hidden = true)
 public record RoomInfoResponse(RRoom room) {}

api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomListResponse.java

@@ -1,7 +1,12 @@
 package ru.dragonestia.picker.api.repository.response;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import ru.dragonestia.picker.api.repository.response.type.RRoom;
 
 import java.util.List;
 
-public record RoomListResponse(String node, List<RRoom.Short> rooms) {}
+@Schema(title = "Room list", hidden = true)
+public record RoomListResponse(
+        @Schema(description = "Node identifier", example = "test-node") String node,
+        List<RRoom.Short> rooms
+) {}

api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RRoom.java

@@ -1,20 +1,33 @@
 package ru.dragonestia.picker.api.repository.response.type;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import ru.dragonestia.picker.api.repository.details.RoomDetails;
 
 import java.beans.Transient;
 import java.util.HashMap;
 import java.util.Map;
 
+@Schema(title = "Room")
 public class RRoom {
 
     public final static int INFINITE_SLOTS = -1;
 
+    @Schema(description = "Room identifier", example = "test-room")
     private String id;
+
+    @Schema(description = "Node identifier", example = "test-node")
     private String nodeId;
+
+    @Schema(description = "Slots for users. -1 - unlimited slots", example = "25")
     private int slots;
+
+    @Schema(description = "Payload. Some data")
     private String payload;
+
+    @Schema(description = "Does picking skip this room?")
     private boolean locked = false;
+
+    @Schema(description = "Additional data requested (Key-Value)")
     private Map<RoomDetails, String> details;
 
     private RRoom() {}
@@ -87,5 +100,12 @@ public class RRoom {
         return false;
     }
 
-    public record Short(String id, String nodeId, int slots, boolean locked, Map<RoomDetails, String> details) {}
+    @Schema(title = "Room (Short)")
+    public record Short(
+            @Schema(description = "Room identifier", example = "test-room") String id,
+            @Schema(description = "Node identifier", example = "test-node") String nodeId,
+            @Schema(description = "Slots for users. -1 - unlimited slots", example = "25") int slots,
+            @Schema(description = "Does picking skip this room?") boolean locked,
+            @Schema(description = "Additional data requested (Key-Value)") Map<RoomDetails, String> details
+    ) {}
 }

app/src/main/java/ru/dragonestia/picker/controller/RoomController.java

@@ -1,8 +1,12 @@
 package ru.dragonestia.picker.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
-import lombok.extern.log4j.Log4j2;
 import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.parameters.P;
 import org.springframework.web.bind.annotation.*;
 import ru.dragonestia.picker.api.exception.NodeNotFoundException;
 import ru.dragonestia.picker.api.exception.RoomNotFoundException;
@@ -15,7 +19,7 @@ import ru.dragonestia.picker.service.NodeService;
 import ru.dragonestia.picker.util.DetailsParser;
 import ru.dragonestia.picker.util.NamingValidator;
 
-@Log4j2
+@Tag(name = "Rooms", description = "Room management")
 @RestController
 @RequestMapping("/nodes/{nodeId}/rooms")
 @RequiredArgsConstructor
@@ -26,10 +30,12 @@ public class RoomController {
     private final NamingValidator namingValidator;
     private final DetailsParser detailsParser;
 
+    @Operation(summary = "Get all rooms from node")
     @GetMapping
-    ResponseEntity<RoomListResponse> all(@PathVariable(name = "nodeId") String nodeId,
+    ResponseEntity<RoomListResponse> all(
-                                         @RequestParam(name = "requiredDetails", required = false, defaultValue = "") String detailsSeq) {
+            @Parameter(description = "Node identifier") @PathVariable(name = "nodeId") String nodeId,
-
+            @Parameter(description = "Required addition data", example = "COUNT_USERS") @RequestParam(name = "requiredDetails", required = false, defaultValue = "") String detailsSeq
+    ) {
         return nodeService.find(nodeId)
                 .map(node -> {
                     var details = detailsParser.parseRoomDetails(detailsSeq);
@@ -38,13 +44,15 @@ public class RoomController {
                 }).orElseThrow(() -> new NodeNotFoundException(nodeId));
     }
 
+    @Operation(summary = "Register new room")
     @PostMapping
-    ResponseEntity<?> register(@PathVariable(name = "nodeId") String nodeId,
+    ResponseEntity<?> register(
-                               @RequestParam(name = "roomId") String roomId,
+            @Parameter(description = "Node identifier") @PathVariable(name = "nodeId") String nodeId,
-                               @RequestParam(name = "slots") int slots,
+            @Parameter(description = "Room identifier") @RequestParam(name = "roomId") String roomId,
-                               @RequestParam(name = "payload") String payload,
+            @Parameter(description = "Maximum users count in room") @RequestParam(name = "slots") int slots,
-                               @RequestParam(name = "locked", defaultValue = "false") boolean locked) {
+            @Parameter(description = "Payload. Some data") @RequestParam(name = "payload") String payload,
-
+            @Parameter(description = "Lock for picking") @RequestParam(name = "locked", defaultValue = "false") boolean locked
+    ) {
         var node = nodeService.find(nodeId).orElseThrow(() -> new NodeNotFoundException(nodeId));
         var room = Room.create(roomId, node, SlotLimit.of(slots), payload);
         room.setLocked(locked);
@@ -53,10 +61,12 @@ public class RoomController {
         return ResponseEntity.ok().build();
     }
 
+    @Operation(summary = "Unregister room")
     @DeleteMapping("/{roomId}")
-    ResponseEntity<?> remove(@PathVariable("nodeId") String nodeId,
+    ResponseEntity<?> remove(
-                             @PathVariable("roomId") String roomId) {
+            @Parameter(description = "Node identifier") @PathVariable("nodeId") String nodeId,
-
+            @Parameter(description = "Room identifier") @PathVariable("roomId") String roomId
+    ) {
         namingValidator.validateNodeId(nodeId);
         namingValidator.validateRoomId(nodeId, roomId);
 
@@ -67,10 +77,12 @@ public class RoomController {
         return ResponseEntity.ok().build();
     }
 
+    @Operation(summary = "Get room details")
     @GetMapping("/{roomId}")
-    ResponseEntity<RoomInfoResponse> info(@PathVariable("nodeId") String nodeId,
+    ResponseEntity<RoomInfoResponse> info(
-                                          @PathVariable("roomId") String roomId) {
+            @Parameter(description = "Node identifier") @PathVariable("nodeId") String nodeId,
-
+            @Parameter(description = "Room identifier") @PathVariable("roomId") String roomId
+    ) {
         namingValidator.validateNodeId(nodeId);
         namingValidator.validateRoomId(nodeId, roomId);
 
@@ -80,11 +92,14 @@ public class RoomController {
                 .orElseThrow(() -> new RoomNotFoundException(nodeId, roomId));
     }
 
+    @Operation(summary = "Lock/unlock room")
+    @ApiResponse(description = "New lock state")
     @PutMapping("/{roomId}/lock")
-    ResponseEntity<Boolean> lockBucket(@PathVariable("nodeId") String nodeId,
+    ResponseEntity<Boolean> lockRoom(
-                                       @PathVariable("roomId") String roomId,
+            @Parameter(description = "Node identifier") @PathVariable("nodeId") String nodeId,
-                                       @RequestParam(name = "newState") boolean value) {
+            @Parameter(description = "Room identifier") @PathVariable("roomId") String roomId,
-
+            @Parameter(description = "New state for Lock property") @RequestParam(name = "newState") boolean value
+    ) {
         namingValidator.validateNodeId(nodeId);
         namingValidator.validateRoomId(nodeId, roomId);