简柏林 / thingskit · Commits

Commit 55e8a4540adcc183b91404944eda213bf7f9769c

Authored by Swoq
Committed by Andrew Shvayka
1 parent 1d87ad73

Swagger API docs for Device Controller

Inline Side-by-side
Showing 1 changed file with 144 additions and 21 deletions
... ... @@ -19,15 +19,11 @@ import com.google.common.util.concurrent.FutureCallback;
19 19 import com.google.common.util.concurrent.Futures;
20 20 import com.google.common.util.concurrent.ListenableFuture;
21 21 import com.google.common.util.concurrent.MoreExecutors;
22   -import io.swagger.annotations.Api;
23 22 import io.swagger.annotations.ApiOperation;
24 23 import io.swagger.annotations.ApiParam;
25   -import io.swagger.annotations.Example;
26   -import io.swagger.annotations.ExampleProperty;
27 24 import lombok.RequiredArgsConstructor;
28 25 import lombok.extern.slf4j.Slf4j;
29 26 import org.springframework.http.HttpStatus;
30   -import org.springframework.http.MediaType;
31 27 import org.springframework.http.ResponseEntity;
32 28 import org.springframework.security.access.prepost.PreAuthorize;
33 29 import org.springframework.web.bind.annotation.PathVariable;
... ... @@ -97,17 +93,35 @@ import static org.thingsboard.server.controller.EdgeController.EDGE_ID;
97 93 @RequiredArgsConstructor
98 94 @Slf4j
99 95 public class DeviceController extends BaseController {
100   - public static final String DEVICE_ID_PARAM_DESCRIPTION = "A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
101 96 private final DeviceBulkImportService deviceBulkImportService;
102 97
  98 + public static final String DEVICE_ID_PARAM_DESCRIPTION = "A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  99 + public static final String DEVICE_PROFILE_ID_DESCRIPTION = "A string value representing the device profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  100 + public static final String TENANT_ID_PARAM_DESCRIPTION = "A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  101 + public static final String EDGE_ID_PARAM_DESCRIPTION = "A string value representing the edge id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  102 + public static final String CUSTOMER_ID_PARAM_DESCRIPTION = "A string value representing the customer id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  103 +
103 104 private static final String DEVICE_ID = "deviceId";
104 105 private static final String DEVICE_NAME = "deviceName";
105 106 private static final String TENANT_ID = "tenantId";
106   -
  107 + private final String PAGE_SIZE_DESCRIPTION = "Maximum amount of entities in a one page";
  108 + private final String PAGE_NUMBER_DESCRIPTION = "Sequence number of page starting from 0";
  109 + private final String DEVICE_TYPE_DESCRIPTION = "Device type as the name of the device profile";
  110 + private final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The search is performed by device special field 'textSearch' represented by device name";
  111 + private final String SORT_PROPERTY_DESCRIPTION = "Property of device to sort by";
  112 + private final String SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, label, type";
  113 + private final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESCENDING (DESC)";
  114 + private final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
  115 + private final String DEVICE_INFO_DESCRIPTION = "Device Info is an object which are an extension of default Device object. " +
  116 + "Apart from Device object, Device Info provides additional information such as customer name and device profile name. ";
  117 +
  118 + @ApiOperation(value = "Get Device (getDeviceById)",
  119 + notes = "If device with given Id exists in the system it will be present in the response, otherwise an empty object will be provided")
107 120 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
108 121 @RequestMapping(value = "/device/{deviceId}", method = RequestMethod.GET)
109 122 @ResponseBody
110   - public Device getDeviceById(@PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
  123 + public Device getDeviceById(@ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
  124 + @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
111 125 checkParameter(DEVICE_ID, strDeviceId);
112 126 try {
113 127 DeviceId deviceId = new DeviceId(toUUID(strDeviceId));
... ... @@ -117,10 +131,12 @@ public class DeviceController extends BaseController {
117 131 }
118 132 }
119 133
  134 + @ApiOperation(value = "Get Device Info (getDeviceInfoById)", notes = DEVICE_INFO_DESCRIPTION)
120 135 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
121 136 @RequestMapping(value = "/device/info/{deviceId}", method = RequestMethod.GET)
122 137 @ResponseBody
123   - public DeviceInfo getDeviceInfoById(@PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
  138 + public DeviceInfo getDeviceInfoById(@ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
  139 + @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
124 140 checkParameter(DEVICE_ID, strDeviceId);
125 141 try {
126 142 DeviceId deviceId = new DeviceId(toUUID(strDeviceId));
... ... @@ -132,7 +148,7 @@ public class DeviceController extends BaseController {
132 148
133 149 @ApiOperation(value = "Create Or Update Device (saveDevice)", notes = "Platform generates random device Id and credentials (access token) during device creation. " +
134 150 "The device id will be present in the response. " +
135   - "Specify the device id when you would like to update the device. Referencing non-existing device Id will cause error.")
  151 + "Specify the device id when you would like to update the device. Referencing non-existing device Id will cause an error.")
136 152 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
137 153 @RequestMapping(value = "/device", method = RequestMethod.POST)
138 154 @ResponseBody
... ... @@ -175,10 +191,13 @@ public class DeviceController extends BaseController {
175 191 }
176 192 }
177 193
  194 + @ApiOperation(value = "Delete device (deleteDevice)",
  195 + notes = "Referencing non-existing device Id will cause an error.")
178 196 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
179 197 @RequestMapping(value = "/device/{deviceId}", method = RequestMethod.DELETE)
180 198 @ResponseStatus(value = HttpStatus.OK)
181   - public void deleteDevice(@PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
  199 + public void deleteDevice(@ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
  200 + @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
182 201 checkParameter(DEVICE_ID, strDeviceId);
183 202 try {
184 203 DeviceId deviceId = new DeviceId(toUUID(strDeviceId));
... ... @@ -204,10 +223,14 @@ public class DeviceController extends BaseController {
204 223 }
205 224 }
206 225
  226 + @ApiOperation(value = "Assign device to customer (assignDeviceToCustomer)",
  227 + notes = "Creates assignment of the device to customer. Customer will be able to query device afterwards.")
207 228 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
208 229 @RequestMapping(value = "/customer/{customerId}/device/{deviceId}", method = RequestMethod.POST)
209 230 @ResponseBody
210   - public Device assignDeviceToCustomer(@PathVariable("customerId") String strCustomerId,
  231 + public Device assignDeviceToCustomer(@ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
  232 + @PathVariable("customerId") String strCustomerId,
  233 + @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
211 234 @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
212 235 checkParameter("customerId", strCustomerId);
213 236 checkParameter(DEVICE_ID, strDeviceId);
... ... @@ -242,7 +265,7 @@ public class DeviceController extends BaseController {
242 265 @RequestMapping(value = "/customer/device/{deviceId}", method = RequestMethod.DELETE)
243 266 @ResponseBody
244 267 public Device unassignDeviceFromCustomer(@ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
245   - @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
  268 + @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
246 269 checkParameter(DEVICE_ID, strDeviceId);
247 270 try {
248 271 DeviceId deviceId = new DeviceId(toUUID(strDeviceId));
... ... @@ -278,7 +301,7 @@ public class DeviceController extends BaseController {
278 301 @RequestMapping(value = "/customer/public/device/{deviceId}", method = RequestMethod.POST)
279 302 @ResponseBody
280 303 public Device assignDeviceToPublicCustomer(@ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
281   - @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
  304 + @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
282 305 checkParameter(DEVICE_ID, strDeviceId);
283 306 try {
284 307 DeviceId deviceId = new DeviceId(toUUID(strDeviceId));
... ... @@ -299,10 +322,13 @@ public class DeviceController extends BaseController {
299 322 }
300 323 }
301 324
  325 + @ApiOperation(value = "Get Device Credentials (getDeviceCredentialsByDeviceId)",
  326 + notes = "If during device creation there wasn't specified any credentials, platform generates random 'ACCESS_TOKEN' credentials.")
302 327 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
303 328 @RequestMapping(value = "/device/{deviceId}/credentials", method = RequestMethod.GET)
304 329 @ResponseBody
305   - public DeviceCredentials getDeviceCredentialsByDeviceId(@PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
  330 + public DeviceCredentials getDeviceCredentialsByDeviceId(@ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
  331 + @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
306 332 checkParameter(DEVICE_ID, strDeviceId);
307 333 try {
308 334 DeviceId deviceId = new DeviceId(toUUID(strDeviceId));
... ... @@ -350,15 +376,24 @@ public class DeviceController extends BaseController {
350 376 }
351 377 }
352 378
  379 + @ApiOperation(value = "Get Tenant Devices (getEdgeDevices)",
  380 + notes = "Returns a page (representation of a bunch) of devices in the possession of tenant. " +
  381 + "You can specify number of parameters to filter the result set of devices. ")
353 382 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
354 383 @RequestMapping(value = "/tenant/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
355 384 @ResponseBody
356 385 public PageData<Device> getTenantDevices(
  386 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
357 387 @RequestParam int pageSize,
  388 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
358 389 @RequestParam int page,
  390 + @ApiParam(value = DEVICE_TYPE_DESCRIPTION)
359 391 @RequestParam(required = false) String type,
  392 + @ApiParam(value = DEVICE_TEXT_SEARCH_DESCRIPTION)
360 393 @RequestParam(required = false) String textSearch,
  394 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = SORT_PROPERTY_ALLOWABLE_VALUES)
361 395 @RequestParam(required = false) String sortProperty,
  396 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
362 397 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
363 398 try {
364 399 TenantId tenantId = getCurrentUser().getTenantId();
... ... @@ -373,17 +408,28 @@ public class DeviceController extends BaseController {
373 408 }
374 409 }
375 410
  411 + @ApiOperation(value = "Get Tenant Device Infos (getTenantDeviceInfos)",
  412 + notes = "Returns a page (representation of a bunch) of devices info objects in the possession of tenant. " +
  413 + "You can specify number of parameters to filter the result set. " + DEVICE_INFO_DESCRIPTION)
376 414 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
377 415 @RequestMapping(value = "/tenant/deviceInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
378 416 @ResponseBody
379 417 public PageData<DeviceInfo> getTenantDeviceInfos(
  418 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
380 419 @RequestParam int pageSize,
  420 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
381 421 @RequestParam int page,
  422 + @ApiParam(value = DEVICE_TYPE_DESCRIPTION)
382 423 @RequestParam(required = false) String type,
  424 + @ApiParam(value = DEVICE_PROFILE_ID_DESCRIPTION)
383 425 @RequestParam(required = false) String deviceProfileId,
  426 + @ApiParam(value = DEVICE_TEXT_SEARCH_DESCRIPTION)
384 427 @RequestParam(required = false) String textSearch,
  428 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = SORT_PROPERTY_ALLOWABLE_VALUES)
385 429 @RequestParam(required = false) String sortProperty,
386   - @RequestParam(required = false) String sortOrder) throws ThingsboardException {
  430 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
  431 + @RequestParam(required = false) String sortOrder
  432 + ) throws ThingsboardException {
387 433 try {
388 434 TenantId tenantId = getCurrentUser().getTenantId();
389 435 PageLink pageLink = createPageLink(pageSize, page, textSearch, sortProperty, sortOrder);
... ... @@ -400,6 +446,9 @@ public class DeviceController extends BaseController {
400 446 }
401 447 }
402 448
  449 + @ApiOperation(value = "Get Tenant Device (getTenantDevice)",
  450 + notes = "Requested device must be in the possession of user that perform request. " +
  451 + "In the Thingsboard platform Device name is an unique property of device. So it can be used to identify the device.")
403 452 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
404 453 @RequestMapping(value = "/tenant/devices", params = {"deviceName"}, method = RequestMethod.GET)
405 454 @ResponseBody
... ... @@ -413,16 +462,26 @@ public class DeviceController extends BaseController {
413 462 }
414 463 }
415 464
  465 + @ApiOperation(value = "Get Customer Devices (getCustomerDevices)",
  466 + notes = "Returns a page (representation of a bunch) of devices objects in the possession of customer. " +
  467 + "You can specify number of parameters to filter the result set. ")
416 468 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
417 469 @RequestMapping(value = "/customer/{customerId}/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
418 470 @ResponseBody
419 471 public PageData<Device> getCustomerDevices(
  472 + @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
420 473 @PathVariable("customerId") String strCustomerId,
  474 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
421 475 @RequestParam int pageSize,
  476 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
422 477 @RequestParam int page,
  478 + @ApiParam(value = DEVICE_TYPE_DESCRIPTION)
423 479 @RequestParam(required = false) String type,
  480 + @ApiParam(value = DEVICE_TEXT_SEARCH_DESCRIPTION)
424 481 @RequestParam(required = false) String textSearch,
  482 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = SORT_PROPERTY_ALLOWABLE_VALUES)
425 483 @RequestParam(required = false) String sortProperty,
  484 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
426 485 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
427 486 checkParameter("customerId", strCustomerId);
428 487 try {
... ... @@ -440,17 +499,28 @@ public class DeviceController extends BaseController {
440 499 }
441 500 }
442 501
  502 + @ApiOperation(value = "Get Customer Device Infos (getCustomerDeviceInfos)",
  503 + notes = "Returns a page (representation of a bunch) of devices info objects in the possession of customer. " +
  504 + "You can specify number of parameters to filter the result set. " + DEVICE_INFO_DESCRIPTION)
443 505 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
444 506 @RequestMapping(value = "/customer/{customerId}/deviceInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
445 507 @ResponseBody
446 508 public PageData<DeviceInfo> getCustomerDeviceInfos(
  509 + @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
447 510 @PathVariable("customerId") String strCustomerId,
  511 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
448 512 @RequestParam int pageSize,
  513 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
449 514 @RequestParam int page,
  515 + @ApiParam(value = DEVICE_TYPE_DESCRIPTION)
450 516 @RequestParam(required = false) String type,
  517 + @ApiParam(value = DEVICE_PROFILE_ID_DESCRIPTION)
451 518 @RequestParam(required = false) String deviceProfileId,
  519 + @ApiParam(value = DEVICE_TEXT_SEARCH_DESCRIPTION)
452 520 @RequestParam(required = false) String textSearch,
  521 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = SORT_PROPERTY_ALLOWABLE_VALUES)
453 522 @RequestParam(required = false) String sortProperty,
  523 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
454 524 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
455 525 checkParameter("customerId", strCustomerId);
456 526 try {
... ... @@ -471,10 +541,13 @@ public class DeviceController extends BaseController {
471 541 }
472 542 }
473 543
  544 + @ApiOperation(value = "Get Devices By Ids (getDevicesByIds)",
  545 + notes = "Requested devices must be in the possession of tenant or customer that performs request. ")
474 546 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
475 547 @RequestMapping(value = "/devices", params = {"deviceIds"}, method = RequestMethod.GET)
476 548 @ResponseBody
477 549 public List<Device> getDevicesByIds(
  550 + @ApiParam(value = "A list of devices ids, separated by comma ','")
478 551 @RequestParam("deviceIds") String[] strDeviceIds) throws ThingsboardException {
479 552 checkArrayParameter("deviceIds", strDeviceIds);
480 553 try {
... ... @@ -521,6 +594,8 @@ public class DeviceController extends BaseController {
521 594 }
522 595 }
523 596
  597 + @ApiOperation(value = "Get Device Types (getDeviceTypes)",
  598 + notes = "Returns all device profile names of all devices in the possession of user that is performing request.")
524 599 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
525 600 @RequestMapping(value = "/device/types", method = RequestMethod.GET)
526 601 @ResponseBody
... ... @@ -535,10 +610,19 @@ public class DeviceController extends BaseController {
535 610 }
536 611 }
537 612
  613 + @ApiOperation(value = "Claim device (claimDevice)",
  614 + notes = "Claiming makes it possible to assign a device to the specific customer using device/server side claiming data (in the form of secret key)." +
  615 + "To make this happen you have to provide unique device name and optional claiming data (it is needed only for device-side claiming)." +
  616 + "Once device is claimed, the customer becomes its owner and customer users may access device data as well as control the device. \n" +
  617 + "In order to enable claiming devices feature a system parameter security.claim.allowClaimingByDefault should be set to true, " +
  618 + "otherwise a server-side claimingAllowed attribute with the value true is obligatory for provisioned devices. \n" +
  619 + "See official documentation for more details regarding claiming.")
538 620 @PreAuthorize("hasAuthority('CUSTOMER_USER')")
539 621 @RequestMapping(value = "/customer/device/{deviceName}/claim", method = RequestMethod.POST)
540 622 @ResponseBody
541   - public DeferredResult<ResponseEntity> claimDevice(@PathVariable(DEVICE_NAME) String deviceName,
  623 + public DeferredResult<ResponseEntity> claimDevice(@ApiParam(value = "Unique name of the device which is going to be claimed")
  624 + @PathVariable(DEVICE_NAME) String deviceName,
  625 + @ApiParam(value = "Claiming request which can optionally contain secret key")
542 626 @RequestBody(required = false) ClaimRequest claimRequest) throws ThingsboardException {
543 627 checkParameter(DEVICE_NAME, deviceName);
544 628 try {
... ... @@ -589,10 +673,13 @@ public class DeviceController extends BaseController {
589 673 }
590 674 }
591 675
  676 + @ApiOperation(value = "Reclaim device (reClaimDevice)",
  677 + notes = "Reclaiming means the device will be unassigned from the customer and the device will be available for claiming again.")
592 678 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
593 679 @RequestMapping(value = "/customer/device/{deviceName}/claim", method = RequestMethod.DELETE)
594 680 @ResponseStatus(value = HttpStatus.OK)
595   - public DeferredResult<ResponseEntity> reClaimDevice(@PathVariable(DEVICE_NAME) String deviceName) throws ThingsboardException {
  681 + public DeferredResult<ResponseEntity> reClaimDevice(@ApiParam(value = "Unique name of the device which is going to be reclaimed")
  682 + @PathVariable(DEVICE_NAME) String deviceName) throws ThingsboardException {
596 683 checkParameter(DEVICE_NAME, deviceName);
597 684 try {
598 685 final DeferredResult<ResponseEntity> deferredResult = new DeferredResult<>();
... ... @@ -640,10 +727,14 @@ public class DeviceController extends BaseController {
640 727 return DataConstants.DEFAULT_SECRET_KEY;
641 728 }
642 729
  730 + @ApiOperation(value = "Assign device to tenant (assignDeviceToTenant)",
  731 + notes = "Creates assignment of the device to tenant. Thereafter tenant will be able to reassign the device to a customer.")
643 732 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
644 733 @RequestMapping(value = "/tenant/{tenantId}/device/{deviceId}", method = RequestMethod.POST)
645 734 @ResponseBody
646   - public Device assignDeviceToTenant(@PathVariable(TENANT_ID) String strTenantId,
  735 + public Device assignDeviceToTenant(@ApiParam(value = TENANT_ID_PARAM_DESCRIPTION)
  736 + @PathVariable(TENANT_ID) String strTenantId,
  737 + @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
647 738 @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
648 739 checkParameter(TENANT_ID, strTenantId);
649 740 checkParameter(DEVICE_ID, strDeviceId);
... ... @@ -690,10 +781,17 @@ public class DeviceController extends BaseController {
690 781 return metaData;
691 782 }
692 783
  784 + @ApiOperation(value = "Assign device to edge (assignDeviceToEdge)",
  785 + notes = "Creates assignment of an existing device to an instance of The ThingsBoard Edge. " +
  786 + "The ThingsBoard Edge is a ThingsBoard’s software product for edge computing. " +
  787 + "It allows bringing data analysis and management to the edge, while seamlessly synchronizing with ThingsBoard CE/PE server (cloud). " +
  788 + "See official documentation for more details regarding provisioning the edge on ThingsBoard server")
693 789 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
694 790 @RequestMapping(value = "/edge/{edgeId}/device/{deviceId}", method = RequestMethod.POST)
695 791 @ResponseBody
696   - public Device assignDeviceToEdge(@PathVariable(EDGE_ID) String strEdgeId,
  792 + public Device assignDeviceToEdge(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION)
  793 + @PathVariable(EDGE_ID) String strEdgeId,
  794 + @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
697 795 @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
698 796 checkParameter(EDGE_ID, strEdgeId);
699 797 checkParameter(DEVICE_ID, strDeviceId);
... ... @@ -724,10 +822,14 @@ public class DeviceController extends BaseController {
724 822 }
725 823 }
726 824
  825 + @ApiOperation(value = "Unassign device from edge (unassignDeviceFromEdge)",
  826 + notes = "Clears assignment of the device to the edge")
727 827 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
728 828 @RequestMapping(value = "/edge/{edgeId}/device/{deviceId}", method = RequestMethod.DELETE)
729 829 @ResponseBody
730   - public Device unassignDeviceFromEdge(@PathVariable(EDGE_ID) String strEdgeId,
  830 + public Device unassignDeviceFromEdge(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION)
  831 + @PathVariable(EDGE_ID) String strEdgeId,
  832 + @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION)
731 833 @PathVariable(DEVICE_ID) String strDeviceId) throws ThingsboardException {
732 834 checkParameter(EDGE_ID, strEdgeId);
733 835 checkParameter(DEVICE_ID, strDeviceId);
... ... @@ -758,18 +860,30 @@ public class DeviceController extends BaseController {
758 860 }
759 861 }
760 862
  863 + @ApiOperation(value = "Get devices assigned to edge (getEdgeDevices)",
  864 + notes = "Returns a page (representation of a bunch) of devices assigned to edge. " +
  865 + "You can specify number of parameters to filter the result set of devices. ")
761 866 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
762 867 @RequestMapping(value = "/edge/{edgeId}/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
763 868 @ResponseBody
764 869 public PageData<Device> getEdgeDevices(
  870 + @ApiParam(value = EDGE_ID_PARAM_DESCRIPTION)
765 871 @PathVariable(EDGE_ID) String strEdgeId,
  872 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
766 873 @RequestParam int pageSize,
  874 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
767 875 @RequestParam int page,
  876 + @ApiParam(value = DEVICE_TYPE_DESCRIPTION)
768 877 @RequestParam(required = false) String type,
  878 + @ApiParam(value = DEVICE_TEXT_SEARCH_DESCRIPTION)
769 879 @RequestParam(required = false) String textSearch,
  880 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = SORT_PROPERTY_ALLOWABLE_VALUES)
770 881 @RequestParam(required = false) String sortProperty,
  882 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
771 883 @RequestParam(required = false) String sortOrder,
  884 + @ApiParam(value = "Timestamp. Devices with creation time before it won't be queried")
772 885 @RequestParam(required = false) Long startTime,
  886 + @ApiParam(value = "Timestamp. Devices with creation time after it won't be queried")
773 887 @RequestParam(required = false) Long endTime) throws ThingsboardException {
774 888 checkParameter(EDGE_ID, strEdgeId);
775 889 try {
... ... @@ -801,10 +915,17 @@ public class DeviceController extends BaseController {
801 915 }
802 916 }
803 917
  918 + @ApiOperation(value = "Count devices by device profile (countByDeviceProfileAndEmptyOtaPackage)",
  919 + notes = "The Thingsboard platform gives an ability to load OTA (over-the-air) packages to devices. " +
  920 + "It can be done in two different ways: device scope or device profile scope." +
  921 + "In the response you will find the number of devices with specified device profile, but without previously defined device scope OTA package. " +
  922 + "It can be useful when you want to define number of devices that will be affected with future OTA package")
804 923 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
805 924 @RequestMapping(value = "/devices/count/{otaPackageType}/{deviceProfileId}", method = RequestMethod.GET)
806 925 @ResponseBody
807   - public Long countByDeviceProfileAndEmptyOtaPackage(@PathVariable("otaPackageType") String otaPackageType,
  926 + public Long countByDeviceProfileAndEmptyOtaPackage(@ApiParam(value = "OTA package type", allowableValues = "FIRMWARE, SOFTWARE")
  927 + @PathVariable("otaPackageType") String otaPackageType,
  928 + @ApiParam(value = "Device Profile Id. I.g. '784f394c-42b6-435a-983c-b7beff2784f9'")
808 929 @PathVariable("deviceProfileId") String deviceProfileId) throws ThingsboardException {
809 930 checkParameter("OtaPackageType", otaPackageType);
810 931 checkParameter("DeviceProfileId", deviceProfileId);
... ... @@ -818,6 +939,8 @@ public class DeviceController extends BaseController {
818 939 }
819 940 }
820 941
  942 + @ApiOperation(value = "Import the bulk of devices (processDevicesBulkImport)",
  943 + notes = "There's an ability to import the bulk of devices using the only .csv file.")
821 944 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
822 945 @PostMapping("/device/bulk_import")
823 946 public BulkImportResult<Device> processDevicesBulkImport(@RequestBody BulkImportRequest request) throws Exception {
... ...