Documented Nodes

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'
 }

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<String, String> details) {}
+@Schema(
+        name = "ErrorResponse",
+        description = "Response with error info"
+)
+public record ErrorResponse(String errorId,
+                            String message,
+                            Map<String, String> details) {}

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) {}

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<RNode> nodes) {}

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<NodeDetails, String> details;
 
     private RNode() {}

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,
+    ResponseEntity<?> registerNode(
-                                      @RequestParam(name = "method") PickingMode method) {
+            @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<NodeDetailsResponse> nodeDetails(@PathVariable("nodeId") String nodeId) {
+    ResponseEntity<NodeDetailsResponse> 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,
+    ResponseEntity<?> pickRoom(
-                               @RequestParam(name = "userIds") String userIds) {
+            @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));