From 2d1bf1434bfc2e1e2c367db3e49a5a15a8b3bab4 Mon Sep 17 00:00:00 2001 From: ScarletRedMan Date: Wed, 14 Feb 2024 22:07:43 +0700 Subject: [PATCH] Documented Nodes --- api/build.gradle | 2 ++ .../repository/response/ErrorResponse.java | 10 +++++- .../response/NodeDetailsResponse.java | 2 ++ .../repository/response/NodeListResponse.java | 2 ++ .../api/repository/response/type/RNode.java | 7 ++++ .../picker/controller/NodeController.java | 34 ++++++++++++++----- 6 files changed, 48 insertions(+), 9 deletions(-) diff --git a/api/build.gradle b/api/build.gradle index 9b70e7e..90122b8 100644 --- a/api/build.gradle +++ b/api/build.gradle @@ -7,6 +7,8 @@ repositories { } dependencies { + implementation 'io.swagger.core.v3:swagger-annotations:2.2.20' + testImplementation platform('org.junit:junit-bom:5.9.1') testImplementation 'org.junit.jupiter:junit-jupiter' } diff --git a/api/src/main/java/ru/dragonestia/picker/api/repository/response/ErrorResponse.java b/api/src/main/java/ru/dragonestia/picker/api/repository/response/ErrorResponse.java index 7b2b5e5..cb23d04 100644 --- a/api/src/main/java/ru/dragonestia/picker/api/repository/response/ErrorResponse.java +++ b/api/src/main/java/ru/dragonestia/picker/api/repository/response/ErrorResponse.java @@ -1,5 +1,13 @@ package ru.dragonestia.picker.api.repository.response; +import io.swagger.v3.oas.annotations.media.Schema; + import java.util.Map; -public record ErrorResponse(String errorId, String message, Map details) {} +@Schema( + name = "ErrorResponse", + description = "Response with error info" +) +public record ErrorResponse(String errorId, + String message, + Map details) {} diff --git a/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeDetailsResponse.java b/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeDetailsResponse.java index 06f3cdd..e9ffdb0 100644 --- a/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeDetailsResponse.java +++ b/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeDetailsResponse.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.RNode; +@Schema(title = "Node details", hidden = true) public record NodeDetailsResponse(RNode node) {} diff --git a/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeListResponse.java b/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeListResponse.java index de92e0d..9b3c02f 100644 --- a/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeListResponse.java +++ b/api/src/main/java/ru/dragonestia/picker/api/repository/response/NodeListResponse.java @@ -1,7 +1,9 @@ package ru.dragonestia.picker.api.repository.response; +import io.swagger.v3.oas.annotations.media.Schema; import ru.dragonestia.picker.api.repository.response.type.RNode; import java.util.List; +@Schema(title = "List of nodes", hidden = true) public record NodeListResponse(List nodes) {} diff --git a/api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RNode.java b/api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RNode.java index f34e88e..bfc1812 100644 --- a/api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RNode.java +++ b/api/src/main/java/ru/dragonestia/picker/api/repository/response/type/RNode.java @@ -1,15 +1,22 @@ package ru.dragonestia.picker.api.repository.response.type; +import io.swagger.v3.oas.annotations.media.Schema; import ru.dragonestia.picker.api.repository.response.type.type.PickingMode; import ru.dragonestia.picker.api.repository.details.NodeDetails; import java.util.HashMap; import java.util.Map; +@Schema(title = "Node") public class RNode { + @Schema(description = "Node identifier", example = "test-node") private String id; + + @Schema(description = "Picking mode method for users between rooms", example = "LEAST_PICKED") private PickingMode mode; + + @Schema(description = "Additional data requested (Key-Value)") private Map details; private RNode() {} diff --git a/app/src/main/java/ru/dragonestia/picker/controller/NodeController.java b/app/src/main/java/ru/dragonestia/picker/controller/NodeController.java index ca22b0f..a8e2932 100644 --- a/app/src/main/java/ru/dragonestia/picker/controller/NodeController.java +++ b/app/src/main/java/ru/dragonestia/picker/controller/NodeController.java @@ -1,5 +1,8 @@ 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.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; @@ -15,6 +18,7 @@ import ru.dragonestia.picker.util.NamingValidator; import java.util.Arrays; +@Tag(name = "Nodes", description = "Node management") @RestController @RequestMapping("/nodes") @RequiredArgsConstructor @@ -25,21 +29,30 @@ public class NodeController { private final DetailsParser detailsParser; private final NamingValidator namingValidator; + @Operation(summary = "Get all nodes") @GetMapping - NodeListResponse allNodes(@RequestParam(name = "requiredDetails", required = false, defaultValue = "") String detailsSeq) { + NodeListResponse allNodes( + @RequestParam(name = "requiredDetails", required = false, defaultValue = "") String detailsSeq + ) { return new NodeListResponse(nodeService.getAllNodesWithDetailsResponse(detailsParser.parseNodeDetails(detailsSeq))); } + @Operation(summary = "Register new node") @PostMapping - ResponseEntity registerNode(@RequestParam(name = "nodeId") String nodeId, - @RequestParam(name = "method") PickingMode method) { + ResponseEntity registerNode( + @Parameter(description = "Node identifier") @RequestParam(name = "nodeId") String nodeId, + @Parameter(description = "Picking mode method") @RequestParam(name = "method") PickingMode method + ) { nodeService.create(new Node(nodeId, method)); return ResponseEntity.ok().build(); } + @Operation(summary = "Get node details") @GetMapping("/{nodeId}") - ResponseEntity nodeDetails(@PathVariable("nodeId") String nodeId) { + ResponseEntity nodeDetails( + @Parameter(description = "Node identifier") @PathVariable("nodeId") String nodeId + ) { namingValidator.validateNodeId(nodeId); return nodeService.find(nodeId) @@ -47,18 +60,23 @@ public class NodeController { .orElseThrow(() -> new NodeNotFoundException(nodeId)); } + @Operation(summary = "Unregister node") @DeleteMapping("/{nodeId}") - ResponseEntity removeNode(@PathVariable("nodeId") String nodeId) { + ResponseEntity removeNode( + @Parameter(description = "Node identifier") @PathVariable("nodeId") String nodeId + ) { namingValidator.validateNodeId(nodeId); nodeService.find(nodeId).ifPresent(nodeService::remove); return ResponseEntity.ok().build(); } + @Operation(summary = "Pick node for users") @PostMapping("/{nodeId}/pick") - ResponseEntity pickRoom(@PathVariable("nodeId") String nodeId, - @RequestParam(name = "userIds") String userIds) { - + ResponseEntity pickRoom( + @Parameter(description = "Node identifier") @PathVariable("nodeId") String nodeId, + @Parameter(description = "Users to add", example = "user1,user3,user3") @RequestParam(name = "userIds") String userIds + ) { namingValidator.validateNodeId(nodeId); var node = nodeService.find(nodeId).orElseThrow(() -> new NodeNotFoundException(nodeId));