From 340fd3e7f6c95835411b2623499c1d61c41aef52 Mon Sep 17 00:00:00 2001 From: ScarletRedMan Date: Wed, 14 Feb 2024 23:17:58 +0700 Subject: [PATCH] Documented Rooms --- .../repository/response/RoomInfoResponse.java | 2 + .../repository/response/RoomListResponse.java | 7 ++- .../api/repository/response/type/RRoom.java | 22 ++++++- .../picker/controller/RoomController.java | 57 ++++++++++++------- 4 files changed, 65 insertions(+), 23 deletions(-) diff --git a/api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomInfoResponse.java b/api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomInfoResponse.java index 52e5820..c3ec645 100644 --- a/api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomInfoResponse.java +++ b/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) {} diff --git a/api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomListResponse.java b/api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomListResponse.java index a617430..097dcae 100644 --- a/api/src/main/java/ru/dragonestia/picker/api/repository/response/RoomListResponse.java +++ b/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 rooms) {} +@Schema(title = "Room list", hidden = true) +public record RoomListResponse( + @Schema(description = "Node identifier", example = "test-node") String node, + List rooms +) {} diff --git a/api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RRoom.java b/api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RRoom.java index c4f88c6..4d83f49 100644 --- a/api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RRoom.java +++ b/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 details; private RRoom() {} @@ -87,5 +100,12 @@ public class RRoom { return false; } - public record Short(String id, String nodeId, int slots, boolean locked, Map 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 details + ) {} } diff --git a/app/src/main/java/ru/dragonestia/picker/controller/RoomController.java b/app/src/main/java/ru/dragonestia/picker/controller/RoomController.java index 66cc8c7..b3c26d7 100644 --- a/app/src/main/java/ru/dragonestia/picker/controller/RoomController.java +++ b/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 all(@PathVariable(name = "nodeId") String nodeId, - @RequestParam(name = "requiredDetails", required = false, defaultValue = "") String detailsSeq) { - + ResponseEntity all( + @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, - @RequestParam(name = "roomId") String roomId, - @RequestParam(name = "slots") int slots, - @RequestParam(name = "payload") String payload, - @RequestParam(name = "locked", defaultValue = "false") boolean locked) { - + ResponseEntity register( + @Parameter(description = "Node identifier") @PathVariable(name = "nodeId") String nodeId, + @Parameter(description = "Room identifier") @RequestParam(name = "roomId") String roomId, + @Parameter(description = "Maximum users count in room") @RequestParam(name = "slots") int slots, + @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, - @PathVariable("roomId") String roomId) { - + ResponseEntity remove( + @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 info(@PathVariable("nodeId") String nodeId, - @PathVariable("roomId") String roomId) { - + ResponseEntity info( + @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 lockBucket(@PathVariable("nodeId") String nodeId, - @PathVariable("roomId") String roomId, - @RequestParam(name = "newState") boolean value) { - + ResponseEntity lockRoom( + @Parameter(description = "Node identifier") @PathVariable("nodeId") String nodeId, + @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);