Documentation for PageData, DeviceSearchQuery and DeviceInfo

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

@@ -154,7 +154,9 @@ import static org.thingsboard.server.dao.service.Validator.validateId;
 public abstract class BaseController {
 
     /*Swagger UI description*/
-    public static final String PAGE_DATA_PARAMETERS = "You can specify parameters to filter the results. ";
+    public static final String PAGE_DATA_PARAMETERS = "You can specify parameters to filter the results. " +
+            "The result is wrapped with PageData object that allows you to iterate over result set using pagination. " +
+            "See the 'Model' tab of the Response Class for more details. ";
     public static final String DEVICE_ID_PARAM_DESCRIPTION = "A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String DEVICE_PROFILE_ID_DESCRIPTION = "A string value representing the device profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String TENANT_ID_PARAM_DESCRIPTION = "A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";

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

@@ -363,7 +363,7 @@ public class DeviceController extends BaseController {
 
     @ApiOperation(value = "Get Tenant Devices (getEdgeDevices)",
             notes = "Returns a page of devices owned by tenant. " +
-                    "You can specify number of parameters to filter the result set of devices. ")
+                    PAGE_DATA_PARAMETERS)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
@@ -527,7 +527,7 @@ public class DeviceController extends BaseController {
     }
 
     @ApiOperation(value = "Get Devices By Ids (getDevicesByIds)",
-            notes = "Requested devices must be in the possession of tenant or customer that performs request. ")
+            notes = "Requested devices must be owned by tenant or assigned to customer which user is performing the request. ")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/devices", params = {"deviceIds"}, method = RequestMethod.GET)
     @ResponseBody
@@ -555,6 +555,10 @@ public class DeviceController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Find related devices (findByQuery)",
+            notes = "Returns all devices that are related to the specific entity. " +
+                    "The entity id, relation type, device types, depth of the search, and other query parameters defined using complex 'DeviceSearchQuery' object. " +
+                    "See 'Model' tab of the Parameters for more info.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/devices", method = RequestMethod.POST)
     @ResponseBody
@@ -580,7 +584,7 @@ public class DeviceController extends BaseController {
     }
 
     @ApiOperation(value = "Get Device Types (getDeviceTypes)",
-            notes = "Returns all device profile names of all devices in the possession of user that is performing request.")
+            notes = "Returns a set of unique device profile names based on devices that are either owned by the tenant or assigned to the customer which user is performing the request.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/device/types", method = RequestMethod.GET)
     @ResponseBody
@@ -846,7 +850,7 @@ public class DeviceController extends BaseController {
 
     @ApiOperation(value = "Get devices assigned to edge (getEdgeDevices)",
             notes = "Returns a page of devices assigned to edge. " +
-                    "You can specify number of parameters to filter the result set of devices. ")
+                    PAGE_DATA_PARAMETERS)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edge/{edgeId}/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody

common/data/src/main/java/org/thingsboard/server/common/data/DeviceInfo.java

@@ -15,14 +15,20 @@
  */
 package org.thingsboard.server.common.data;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.id.DeviceId;
 
+@ApiModel
 @Data
 public class DeviceInfo extends Device {
 
+    @ApiModelProperty(position = 13, value = "Title of the Customer that owns the device.", readOnly = true)
     private String customerTitle;
+    @ApiModelProperty(position = 14, value = "Indicates special 'Public' Customer that is auto-generated to use the devices on public dashboards.", readOnly = true)
     private boolean customerIsPublic;
+    @ApiModelProperty(position = 15, value = "Name of the corresponding Device Profile.", readOnly = true)
     private String deviceProfileName;
 
     public DeviceInfo() {

common/data/src/main/java/org/thingsboard/server/common/data/device/DeviceSearchQuery.java

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.common.data.device;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.EntityType;
 import org.thingsboard.server.common.data.relation.EntityRelation;
@@ -25,11 +27,15 @@ import org.thingsboard.server.common.data.relation.RelationsSearchParameters;
 import java.util.Collections;
 import java.util.List;
 
+@ApiModel
 @Data
 public class DeviceSearchQuery {
 
+    @ApiModelProperty(position = 3, value = "Main search parameters.")
     private RelationsSearchParameters parameters;
+    @ApiModelProperty(position = 1, value = "Type of the relation between root entity and device (e.g. 'Contains' or 'Manages').")
     private String relationType;
+    @ApiModelProperty(position = 2, value = "Array of device types to filter the related entities (e.g. 'Temperature Sensor', 'Smoke Sensor').")
     private List<String> deviceTypes;
 
     public EntityRelationsQuery toEntitySearchQuery() {

common/data/src/main/java/org/thingsboard/server/common/data/page/PageData.java

@@ -17,12 +17,15 @@ package org.thingsboard.server.common.data.page;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 
 import java.util.Collections;
 import java.util.List;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
+@ApiModel
 public class PageData<T> {
 
     private final List<T> data;
@@ -45,18 +48,22 @@ public class PageData<T> {
         this.hasNext = hasNext;
     }
 
+    @ApiModelProperty(position = 1, value = "Array of the entities.", readOnly = true)
     public List<T> getData() {
         return data;
     }
 
+    @ApiModelProperty(position = 2, value = "Total number of available pages. Calculated based on the 'pageSize' request parameter and total number of entities that match search criteria.", readOnly = true)
     public int getTotalPages() {
         return totalPages;
     }
 
+    @ApiModelProperty(position = 3, value = "Total number of elements in all available pages.", readOnly = true)
     public long getTotalElements() {
         return totalElements;
     }
 
+    @ApiModelProperty(position = 4, value = "'false' value indicates the end of the result set.", readOnly = true)
     @JsonProperty("hasNext")
     public boolean hasNext() {
         return hasNext;

common/data/src/main/java/org/thingsboard/server/common/data/relation/RelationsSearchParameters.java

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.common.data.relation;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import org.thingsboard.server.common.data.EntityType;
@@ -26,15 +28,22 @@ import java.util.UUID;
 /**
  * Created by ashvayka on 03.05.17.
  */
+@ApiModel
 @Data
 @AllArgsConstructor
 public class RelationsSearchParameters {
 
+    @ApiModelProperty(position = 1, value = "Root entity id to start search from.")
     private UUID rootId;
+    @ApiModelProperty(position = 2, value = "Type of the root entity.")
     private EntityType rootType;
+    @ApiModelProperty(position = 3, value = "Type of the root entity.")
     private EntitySearchDirection direction;
+    @ApiModelProperty(position = 4, value = "Type of the relation.")
     private RelationTypeGroup relationTypeGroup;
+    @ApiModelProperty(position = 5, value = "Maximum level of the search depth.")
     private int maxLevel = 1;
+    @ApiModelProperty(position = 6, value = "Fetch entities that match the last level of search. Useful to find Devices that are strictly 'maxLevel' relations away from the root entity.")
     private boolean fetchLastLevelOnly;
 
     public RelationsSearchParameters(EntityId entityId, EntitySearchDirection direction, int maxLevel, boolean fetchLastLevelOnly) {