added queue swagger doc

application/src/main/java/org/thingsboard/server/controller/ControllerConstants.java

@@ -112,6 +112,10 @@ public class ControllerConstants {
     protected static final String DEVICE_PROFILE_INFO_DESCRIPTION = "Device Profile Info is a lightweight object that includes main information about Device Profile excluding the heavyweight configuration object. ";
     protected static final String QUEUE_SERVICE_TYPE_DESCRIPTION = "Service type (implemented only for the TB-RULE-ENGINE)";
     protected static final String QUEUE_SERVICE_TYPE_ALLOWABLE_VALUES = "TB-RULE-ENGINE, TB-CORE, TB-TRANSPORT, JS-EXECUTOR";
+    protected static final String QUEUE_QUEUE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'substring' filter based on the queue name.";
+    protected static final String QUEUE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, topic";
+    protected static final String QUEUE_ID_PARAM_DESCRIPTION = "A string value representing the queue id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
+    protected static final String QUEUE_NAME_PARAM_DESCRIPTION = "A string value representing the queue id. For example, 'Main'";
     protected static final String OTA_PACKAGE_INFO_DESCRIPTION = "OTA Package Info is a lightweight object that includes main information about the OTA Package excluding the heavyweight data. ";
     protected static final String OTA_PACKAGE_DESCRIPTION = "OTA Package is a heavyweight object that includes main information about the OTA Package and also data. ";
     protected static final String OTA_PACKAGE_CHECKSUM_ALGORITHM_ALLOWABLE_VALUES = "MD5, SHA256, SHA384, SHA512, CRC32, MURMUR3_32, MURMUR3_128";

application/src/main/java/org/thingsboard/server/controller/QueueController.java

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.controller;
 
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -37,6 +39,22 @@ import org.thingsboard.server.service.security.permission.Resource;
 
 import java.util.UUID;
 
+import static org.thingsboard.server.controller.ControllerConstants.PAGE_DATA_PARAMETERS;
+import static org.thingsboard.server.controller.ControllerConstants.PAGE_NUMBER_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.PAGE_SIZE_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.QUEUE_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.QUEUE_NAME_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.QUEUE_QUEUE_TEXT_SEARCH_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.QUEUE_SERVICE_TYPE_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.QUEUE_SERVICE_TYPE_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.QUEUE_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.SORT_ORDER_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.SORT_ORDER_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.SORT_PROPERTY_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.SYSTEM_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.UUID_WIKI_LINK;
+
 @RestController
 @TbCoreComponent
 @RequestMapping("/api")
@@ -45,14 +63,23 @@ public class QueueController extends BaseController {
 
     private final TbQueueService tbQueueService;
 
+    @ApiOperation(value = "Get Queues (getTenantQueuesByServiceType)",
+            notes = "Returns a page of queues registered in the platform. " +
+                    PAGE_DATA_PARAMETERS + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/queues", params = {"serviceType", "pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
-    public PageData<Queue> getTenantQueuesByServiceType(@RequestParam String serviceType,
+    public PageData<Queue> getTenantQueuesByServiceType(@ApiParam(value = QUEUE_SERVICE_TYPE_DESCRIPTION, allowableValues = QUEUE_SERVICE_TYPE_ALLOWABLE_VALUES, required = true)
+                                                        @RequestParam String serviceType,
+                                                        @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
                                                         @RequestParam int pageSize,
+                                                        @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
                                                         @RequestParam int page,
+                                                        @ApiParam(value = QUEUE_QUEUE_TEXT_SEARCH_DESCRIPTION)
                                                         @RequestParam(required = false) String textSearch,
+                                                        @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = QUEUE_SORT_PROPERTY_ALLOWABLE_VALUES)
                                                         @RequestParam(required = false) String sortProperty,
+                                                        @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
                                                         @RequestParam(required = false) String sortOrder) throws ThingsboardException {
         checkParameter("serviceType", serviceType);
         PageLink pageLink = createPageLink(pageSize, page, textSearch, sortProperty, sortOrder);
@@ -65,29 +92,44 @@ public class QueueController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Queue (getQueueById)",
+            notes = "Fetch the Queue object based on the provided Queue Id. " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/queues/{queueId}", method = RequestMethod.GET)
     @ResponseBody
-    public Queue getQueueById(@PathVariable("queueId") String queueIdStr) throws ThingsboardException {
+    public Queue getQueueById(@ApiParam(value = QUEUE_ID_PARAM_DESCRIPTION)
+                              @PathVariable("queueId") String queueIdStr) throws ThingsboardException {
         checkParameter("queueId", queueIdStr);
         QueueId queueId = new QueueId(UUID.fromString(queueIdStr));
         checkQueueId(queueId, Operation.READ);
         return checkNotNull(queueService.findQueueById(getTenantId(), queueId));
     }
 
+    @ApiOperation(value = "Get Queue (getQueueByName)",
+            notes = "Fetch the Queue object based on the provided Queue name. " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/queues/name/{queueName}", method = RequestMethod.GET)
     @ResponseBody
-    public Queue getQueueByName(@PathVariable("queueName") String queueName) throws ThingsboardException {
+    public Queue getQueueByName(@ApiParam(value = QUEUE_NAME_PARAM_DESCRIPTION)
+                                @PathVariable("queueName") String queueName) throws ThingsboardException {
         checkParameter("queueName", queueName);
         return checkNotNull(queueService.findQueueByTenantIdAndName(getTenantId(), queueName));
     }
 
+    @ApiOperation(value = "Create Or Update Queue (saveQueue)",
+            notes = "Create or update the Queue. When creating queue, platform generates Queue Id as " + UUID_WIKI_LINK +
+                    "Specify existing Queue id to update the queue. " +
+                    "Referencing non-existing Queue Id will cause 'Not Found' error." +
+                    "\n\nQueue name is unique in the scope of sysadmin. " +
+                    "Remove 'id', 'tenantId' from the request body example (below) to create new Queue entity. " +
+                    SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/queues", params = {"serviceType"}, method = RequestMethod.POST)
     @ResponseBody
 
-    public Queue saveQueue(@RequestBody Queue queue,
+    public Queue saveQueue(@ApiParam(value = "A JSON value representing the queue.")
+                           @RequestBody Queue queue,
+                           @ApiParam(value = QUEUE_SERVICE_TYPE_DESCRIPTION, allowableValues = QUEUE_SERVICE_TYPE_ALLOWABLE_VALUES, required = true)
                            @RequestParam String serviceType) throws ThingsboardException {
         checkParameter("serviceType", serviceType);
         queue.setTenantId(getCurrentUser().getTenantId());
@@ -106,10 +148,12 @@ public class QueueController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Delete Queue (deleteQueue)", notes = "Deletes the Queue. " + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/queues/{queueId}", method = RequestMethod.DELETE)
     @ResponseBody
-    public void deleteQueue(@PathVariable("queueId") String queueIdStr) throws ThingsboardException {
+    public void deleteQueue(@ApiParam(value = QUEUE_ID_PARAM_DESCRIPTION)
+                            @PathVariable("queueId") String queueIdStr) throws ThingsboardException {
         checkParameter("queueId", queueIdStr);
         QueueId queueId = new QueueId(toUUID(queueIdStr));
         checkQueueId(queueId, Operation.DELETE);