Merge branch 'master' of github.com:thingsboard/thingsboard

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

@@ -25,7 +25,6 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.util.StringUtils;
 import org.springframework.web.context.request.async.DeferredResult;
 import org.thingsboard.common.util.JacksonUtil;
-import org.thingsboard.server.common.data.rpc.RpcError;
 import org.thingsboard.server.common.data.DataConstants;
 import org.thingsboard.server.common.data.audit.ActionType;
 import org.thingsboard.server.common.data.exception.ThingsboardErrorCode;
@@ -34,10 +33,11 @@ import org.thingsboard.server.common.data.id.DeviceId;
 import org.thingsboard.server.common.data.id.EntityId;
 import org.thingsboard.server.common.data.id.TenantId;
 import org.thingsboard.server.common.data.id.UUIDBased;
+import org.thingsboard.server.common.data.rpc.RpcError;
 import org.thingsboard.server.common.data.rpc.ToDeviceRpcRequestBody;
+import org.thingsboard.server.common.msg.rpc.FromDeviceRpcResponse;
 import org.thingsboard.server.common.msg.rpc.ToDeviceRpcRequest;
 import org.thingsboard.server.queue.util.TbCoreComponent;
-import org.thingsboard.server.common.msg.rpc.FromDeviceRpcResponse;
 import org.thingsboard.server.service.rpc.LocalRequestMetaData;
 import org.thingsboard.server.service.rpc.TbCoreDeviceRpcService;
 import org.thingsboard.server.service.security.AccessValidator;

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

@@ -15,8 +15,6 @@
  */
 package org.thingsboard.server.controller;
 
-import com.fasterxml.jackson.databind.JsonNode;
-import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
 import io.swagger.annotations.ApiOperation;
 import io.swagger.annotations.ApiParam;
@@ -50,13 +48,13 @@ import org.thingsboard.server.common.data.security.model.SecuritySettings;
 import org.thingsboard.server.common.data.security.model.UserPasswordPolicy;
 import org.thingsboard.server.dao.audit.AuditLogService;
 import org.thingsboard.server.queue.util.TbCoreComponent;
+import org.thingsboard.server.service.security.auth.jwt.RefreshTokenRepository;
+import org.thingsboard.server.service.security.auth.rest.RestAuthenticationDetails;
 import org.thingsboard.server.service.security.model.ActivateUserRequest;
 import org.thingsboard.server.service.security.model.ChangePasswordRequest;
+import org.thingsboard.server.service.security.model.JwtTokenPair;
 import org.thingsboard.server.service.security.model.ResetPasswordEmailRequest;
 import org.thingsboard.server.service.security.model.ResetPasswordRequest;
-import org.thingsboard.server.service.security.auth.jwt.RefreshTokenRepository;
-import org.thingsboard.server.service.security.auth.rest.RestAuthenticationDetails;
-import org.thingsboard.server.service.security.model.JwtTokenPair;
 import org.thingsboard.server.service.security.model.SecurityUser;
 import org.thingsboard.server.service.security.model.UserPrincipal;
 import org.thingsboard.server.service.security.model.token.JwtTokenFactory;

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

@@ -15,7 +15,6 @@
  */
 package org.thingsboard.server.controller;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
 import com.google.common.util.concurrent.FutureCallback;
 import com.google.common.util.concurrent.Futures;
 import com.google.common.util.concurrent.ListenableFuture;
@@ -85,7 +84,6 @@ import javax.annotation.Nullable;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.Map;
 import java.util.UUID;
 import java.util.stream.Collectors;
 
@@ -99,7 +97,6 @@ import static org.thingsboard.server.controller.ControllerConstants.DEVICE_PROFI
 import static org.thingsboard.server.controller.ControllerConstants.DEVICE_SORT_PROPERTY_ALLOWABLE_VALUES;
 import static org.thingsboard.server.controller.ControllerConstants.DEVICE_TEXT_SEARCH_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.DEVICE_TYPE_DESCRIPTION;
-import static org.thingsboard.server.controller.ControllerConstants.DEVICE_WITH_DEVICE_CREDENTIALS_PARAM_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.DEVICE_WITH_DEVICE_CREDENTIALS_PARAM_DESCRIPTION_MARKDOWN;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_ASYNC_FIRST_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_RECEIVE_STEP_DESCRIPTION;

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

@@ -75,11 +75,28 @@ import java.util.concurrent.ExecutionException;
 import java.util.stream.Collectors;
 
 import static org.apache.commons.lang3.StringUtils.isBlank;
-import static org.thingsboard.server.controller.ControllerConstants.*;
+import static org.thingsboard.server.controller.ControllerConstants.CUSTOMER_ID;
+import static org.thingsboard.server.controller.ControllerConstants.CUSTOMER_ID_PARAM_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_ASYNC_FIRST_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_RECEIVE_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_UNASSIGN_ASYNC_FIRST_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_UNASSIGN_RECEIVE_STEP_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.ENTITY_VIEW_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.ENTITY_VIEW_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.ENTITY_VIEW_INFO_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.ENTITY_VIEW_INFO_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.ENTITY_VIEW_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.ENTITY_VIEW_TEXT_SEARCH_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.ENTITY_VIEW_TYPE;
+import static org.thingsboard.server.controller.ControllerConstants.MODEL_DESCRIPTION;
+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.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.TENANT_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
 import static org.thingsboard.server.controller.EdgeController.EDGE_ID;
 
 /**

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

@@ -28,18 +28,14 @@ import org.springframework.web.bind.annotation.RequestMethod;
 import org.springframework.web.bind.annotation.ResponseBody;
 import org.springframework.web.bind.annotation.RestController;
 import org.thingsboard.server.common.data.Device;
-import org.thingsboard.server.common.data.EntityType;
 import org.thingsboard.server.common.data.SaveDeviceWithCredentialsRequest;
-import org.thingsboard.server.common.data.audit.ActionType;
 import org.thingsboard.server.common.data.exception.ThingsboardException;
 import org.thingsboard.server.common.data.lwm2m.ServerSecurityConfig;
 import org.thingsboard.server.common.data.security.DeviceCredentials;
 import org.thingsboard.server.queue.util.TbCoreComponent;
-import org.thingsboard.server.service.security.permission.Resource;
 
 import java.util.Map;
 
-import static org.thingsboard.server.controller.ControllerConstants.DEVICE_WITH_DEVICE_CREDENTIALS_PARAM_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.IS_BOOTSTRAP_SERVER_PARAM_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
 

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

@@ -52,8 +52,22 @@ import javax.annotation.Nullable;
 import java.util.UUID;
 
 import static org.thingsboard.server.common.data.DataConstants.RPC_DELETED;
-
+import static org.thingsboard.server.controller.ControllerConstants.DEVICE_ID;
-import static org.thingsboard.server.controller.ControllerConstants.*;
+import static org.thingsboard.server.controller.ControllerConstants.DEVICE_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.MARKDOWN_CODE_BLOCK_END;
+import static org.thingsboard.server.controller.ControllerConstants.MARKDOWN_CODE_BLOCK_START;
+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.RPC_ID;
+import static org.thingsboard.server.controller.ControllerConstants.RPC_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.RPC_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.RPC_STATUS_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.RPC_TEXT_SEARCH_DESCRIPTION;
+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.TENANT_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
 
 @RestController
 @TbCoreComponent

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

@@ -40,7 +40,19 @@ import org.thingsboard.server.queue.util.TbCoreComponent;
 import org.thingsboard.server.service.security.permission.Operation;
 import org.thingsboard.server.service.security.permission.Resource;
 
-import static org.thingsboard.server.controller.ControllerConstants.*;
+import static org.thingsboard.server.controller.ControllerConstants.MARKDOWN_CODE_BLOCK_END;
+import static org.thingsboard.server.controller.ControllerConstants.MARKDOWN_CODE_BLOCK_START;
+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.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.TENANT_PROFILE_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_PROFILE_INFO_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_PROFILE_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_PROFILE_TEXT_SEARCH_DESCRIPTION;
 
 @RestController
 @TbCoreComponent

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

@@ -62,7 +62,25 @@ import org.thingsboard.server.service.security.system.SystemSecurityService;
 import javax.servlet.http.HttpServletRequest;
 import java.util.List;
 
-import static org.thingsboard.server.controller.ControllerConstants.*;
+import static org.thingsboard.server.controller.ControllerConstants.CUSTOMER_ID;
+import static org.thingsboard.server.controller.ControllerConstants.CUSTOMER_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.DEFAULT_DASHBOARD;
+import static org.thingsboard.server.controller.ControllerConstants.HOME_DASHBOARD;
+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.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.TENANT_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_ID;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.USER_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.USER_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.USER_TEXT_SEARCH_DESCRIPTION;
 
 @RequiredArgsConstructor
 @RestController

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

@@ -43,7 +43,9 @@ import org.thingsboard.server.service.security.permission.Resource;
 
 import java.util.List;
 
-import static org.thingsboard.server.controller.ControllerConstants.*;
+import static org.thingsboard.server.controller.ControllerConstants.AVAILABLE_FOR_ANY_AUTHORIZED_USER;
+import static org.thingsboard.server.controller.ControllerConstants.SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.WIDGET_TYPE_ID_PARAM_DESCRIPTION;
 
 @Slf4j
 @RestController

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

@@ -41,7 +41,17 @@ import org.thingsboard.server.service.security.permission.Resource;
 
 import java.util.List;
 
-import static org.thingsboard.server.controller.ControllerConstants.*;
+import static org.thingsboard.server.controller.ControllerConstants.AVAILABLE_FOR_ANY_AUTHORIZED_USER;
+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.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_OR_TENANT_AUTHORITY_PARAGRAPH;
+import static org.thingsboard.server.controller.ControllerConstants.WIDGET_BUNDLE_ID_PARAM_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.WIDGET_BUNDLE_SORT_PROPERTY_ALLOWABLE_VALUES;
+import static org.thingsboard.server.controller.ControllerConstants.WIDGET_BUNDLE_TEXT_SEARCH_DESCRIPTION;
 
 @RestController
 @TbCoreComponent

common/transport/http/src/main/java/org/thingsboard/server/transport/http/DeviceApiController.java

@@ -17,6 +17,8 @@ package org.thingsboard.server.transport.http;
 
 import com.google.gson.JsonObject;
 import com.google.gson.JsonParser;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -68,6 +70,7 @@ import java.util.List;
 import java.util.UUID;
 import java.util.function.Consumer;
 
+
 /**
  * @author Andrew Shvayka
  */
@@ -77,14 +80,70 @@ import java.util.function.Consumer;
 @Slf4j
 public class DeviceApiController implements TbTransportService {
 
+    private static final String MARKDOWN_CODE_BLOCK_START = "\n\n```json\n";
+    private static final String MARKDOWN_CODE_BLOCK_END = "\n```\n\n";
+
+    private static final String REQUIRE_ACCESS_TOKEN = "The API call is designed to be used by device firmware and requires device access token ('deviceToken'). " +
+            "It is not recommended to use this API call by third-party scripts, rule-engine or platform widgets (use 'Telemetry Controller' instead).\n";
+
+    private static final String ATTRIBUTE_PAYLOAD_EXAMPLE = "{\n" +
+            " \"stringKey\":\"value1\", \n" +
+            " \"booleanKey\":true, \n" +
+            " \"doubleKey\":42.0, \n" +
+            " \"longKey\":73, \n" +
+            " \"jsonKey\": {\n" +
+            "    \"someNumber\": 42,\n" +
+            "    \"someArray\": [1,2,3],\n" +
+            "    \"someNestedObject\": {\"key\": \"value\"}\n" +
+            " }\n" +
+            "}";
+
+    protected static final String TS_PAYLOAD = "The request payload is a JSON document with three possible formats:\n\n" +
+            "Simple format without timestamp. In such a case, current server time will be used: \n\n" +
+            MARKDOWN_CODE_BLOCK_START +
+            "{\n" +
+            " \"stringKey\":\"value1\", \n" +
+            " \"booleanKey\":true, \n" +
+            " \"doubleKey\":42.0, \n" +
+            " \"longKey\":73, \n" +
+            " \"jsonKey\": {\n" +
+            "    \"someNumber\": 42,\n" +
+            "    \"someArray\": [1,2,3],\n" +
+            "    \"someNestedObject\": {\"key\": \"value\"}\n" +
+            " }\n" +
+            "}" +
+            MARKDOWN_CODE_BLOCK_END +
+            "\n\n Single JSON object with timestamp: \n\n" +
+            MARKDOWN_CODE_BLOCK_START +
+            "{\"ts\":1634712287000,\"values\":{\"temperature\":26, \"humidity\":87}}" +
+            MARKDOWN_CODE_BLOCK_END +
+            "\n\n JSON array with timestamps: \n\n" +
+            MARKDOWN_CODE_BLOCK_START +
+            "[\n{\"ts\":1634712287000,\"values\":{\"temperature\":26, \"humidity\":87}}, \n{\"ts\":1634712588000,\"values\":{\"temperature\":25, \"humidity\":88}}\n]" +
+            MARKDOWN_CODE_BLOCK_END;
+
+    private static final String ACCESS_TOKEN_PARAM_DESCRIPTION = "Your device access token.";
+
     @Autowired
     private HttpTransportContext transportContext;
 
+    @ApiOperation(value = "Get attributes (getDeviceAttributes)",
+            notes = "Returns all attributes that belong to device. "
+                    + "Use optional 'clientKeys' and/or 'sharedKeys' parameter to return specific attributes. "
+                    + "\n Example of the result: "
+                    + MARKDOWN_CODE_BLOCK_START
+                    + ATTRIBUTE_PAYLOAD_EXAMPLE
+                    + MARKDOWN_CODE_BLOCK_END
+                    + REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/attributes", method = RequestMethod.GET, produces = "application/json")
-    public DeferredResult<ResponseEntity> getDeviceAttributes(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> getDeviceAttributes(
-                                                              @RequestParam(value = "clientKeys", required = false, defaultValue = "") String clientKeys,
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
-                                                              @RequestParam(value = "sharedKeys", required = false, defaultValue = "") String sharedKeys,
+            @PathVariable("deviceToken") String deviceToken,
-                                                              HttpServletRequest httpRequest) {
+            @ApiParam(value = "Comma separated key names for attribute with client scope", required = true, defaultValue = "state")
+            @RequestParam(value = "clientKeys", required = false, defaultValue = "") String clientKeys,
+            @ApiParam(value = "Comma separated key names for attribute with shared scope", required = true, defaultValue = "configuration")
+            @RequestParam(value = "sharedKeys", required = false, defaultValue = "") String sharedKeys) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -106,9 +165,20 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Post attributes (postDeviceAttributes)",
+            notes = "Post client attribute updates on behalf of device. "
+                    + "\n Example of the request: "
+                    + MARKDOWN_CODE_BLOCK_START
+                    + ATTRIBUTE_PAYLOAD_EXAMPLE
+                    + MARKDOWN_CODE_BLOCK_END
+                    + REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/attributes", method = RequestMethod.POST)
-    public DeferredResult<ResponseEntity> postDeviceAttributes(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> postDeviceAttributes(
-                                                               @RequestBody String json, HttpServletRequest request) {
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
+            @PathVariable("deviceToken") String deviceToken,
+            @ApiParam(value = "JSON with attribute key-value pairs. See API call description for example.")
+            @RequestBody String json) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -119,9 +189,17 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Post time-series data (postTelemetry)",
+            notes = "Post time-series data on behalf of device. "
+                    + "\n Example of the request: "
+                    + TS_PAYLOAD
+                    + REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/telemetry", method = RequestMethod.POST)
-    public DeferredResult<ResponseEntity> postTelemetry(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> postTelemetry(
-                                                        @RequestBody String json, HttpServletRequest request) {
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
+            @PathVariable("deviceToken") String deviceToken,
+            @RequestBody String json, HttpServletRequest request) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<ResponseEntity>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -132,9 +210,22 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Save claiming information (claimDevice)",
+            notes = "Saves the information required for user to claim the device. " +
+                    "See more info about claiming in the corresponding 'Claiming devices' platform documentation."
+                    + "\n Example of the request payload: "
+                    + MARKDOWN_CODE_BLOCK_START
+                    + "{\"secretKey\":\"value\", \"durationMs\":60000}"
+                    + MARKDOWN_CODE_BLOCK_END
+                    + "Note: both 'secretKey' and 'durationMs' is optional parameters. " +
+                    "In case the secretKey is not specified, the empty string as a default value is used. In case the durationMs is not specified, the system parameter device.claim.duration is used.\n\n"
+                    + REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/claim", method = RequestMethod.POST)
-    public DeferredResult<ResponseEntity> claimDevice(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> claimDevice(
-                                                      @RequestBody(required = false) String json, HttpServletRequest request) {
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
+            @PathVariable("deviceToken") String deviceToken,
+            @RequestBody(required = false) String json) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -146,10 +237,18 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Subscribe to RPC commands (subscribeToCommands) (Deprecated)",
+            notes = "Subscribes to RPC commands using http long polling. " +
+                    "Deprecated, since long polling is resource and network consuming. " +
+                    "Consider using MQTT or CoAP protocol for light-weight real-time updates. \n\n" +
+                    REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/rpc", method = RequestMethod.GET, produces = "application/json")
-    public DeferredResult<ResponseEntity> subscribeToCommands(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> subscribeToCommands(
-                                                              @RequestParam(value = "timeout", required = false, defaultValue = "0") long timeout,
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
-                                                              HttpServletRequest httpRequest) {
+            @PathVariable("deviceToken") String deviceToken,
+            @ApiParam(value = "Optional timeout of the long poll. Typically less then 60 seconds, since limited on the server side.")
+            @RequestParam(value = "timeout", required = false, defaultValue = "0") long timeout) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -164,10 +263,18 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Reply to RPC commands (replyToCommand)",
+            notes = "Replies to server originated RPC command identified by 'requestId' parameter. The response is arbitrary JSON.\n\n" +
+                    REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/rpc/{requestId}", method = RequestMethod.POST)
-    public DeferredResult<ResponseEntity> replyToCommand(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> replyToCommand(
-                                                         @PathVariable("requestId") Integer requestId,
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
-                                                         @RequestBody String json, HttpServletRequest request) {
+            @PathVariable("deviceToken") String deviceToken,
+            @ApiParam(value = "RPC request id from the incoming RPC request", required = true, defaultValue = "123")
+            @PathVariable("requestId") Integer requestId,
+            @ApiParam(value = "Reply to the RPC request, JSON. For example: {\"status\":\"success\"}", required = true)
+            @RequestBody String json) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<ResponseEntity>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -177,9 +284,23 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Send the RPC command (postRpcRequest)",
+            notes = "Send the RPC request to server. The request payload is a JSON document that contains 'method' and 'params'. For example:" +
+                    MARKDOWN_CODE_BLOCK_START +
+                    "{\"method\": \"sumOnServer\", \"params\":{\"a\":2, \"b\":2}}" +
+                    MARKDOWN_CODE_BLOCK_END +
+                    "The response contains arbitrary JSON with the RPC reply. For example: " +
+                    MARKDOWN_CODE_BLOCK_START +
+                    "{\"result\": 4}" +
+                    MARKDOWN_CODE_BLOCK_END +
+                    REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/rpc", method = RequestMethod.POST)
-    public DeferredResult<ResponseEntity> postRpcRequest(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> postRpcRequest(
-                                                         @RequestBody String json, HttpServletRequest httpRequest) {
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
+            @PathVariable("deviceToken") String deviceToken,
+            @ApiParam(value = "The RPC request JSON", required = true)
+            @RequestBody String json) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<ResponseEntity>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -196,10 +317,18 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Subscribe to attribute updates (subscribeToAttributes) (Deprecated)",
+            notes = "Subscribes to client and shared scope attribute updates using http long polling. " +
+                    "Deprecated, since long polling is resource and network consuming. " +
+                    "Consider using MQTT or CoAP protocol for light-weight real-time updates. \n\n" +
+                    REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/attributes/updates", method = RequestMethod.GET, produces = "application/json")
-    public DeferredResult<ResponseEntity> subscribeToAttributes(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> subscribeToAttributes(
-                                                                @RequestParam(value = "timeout", required = false, defaultValue = "0") long timeout,
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
-                                                                HttpServletRequest httpRequest) {
+            @PathVariable("deviceToken") String deviceToken,
+            @ApiParam(value = "Optional timeout of the long poll. Typically less then 60 seconds, since limited on the server side.")
+            @RequestParam(value = "timeout", required = false, defaultValue = "0") long timeout) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<>();
         transportContext.getTransportService().process(DeviceTransportType.DEFAULT, ValidateDeviceTokenRequestMsg.newBuilder().setToken(deviceToken).build(),
                 new DeviceAuthCallback(transportContext, responseWriter, sessionInfo -> {
@@ -214,26 +343,85 @@ public class DeviceApiController implements TbTransportService {
         return responseWriter;
     }
 
+    @ApiOperation(value = "Get Device Firmware (getFirmware)",
+            notes = "Downloads the current firmware package." +
+                    "When the platform initiates firmware update, " +
+                    "it informs the device by updating the 'fw_title', 'fw_version', 'fw_checksum' and 'fw_checksum_algorithm' shared attributes." +
+                    "The 'fw_title' and 'fw_version' parameters must be supplied in this request to double-check " +
+                    "that the firmware that device is downloading matches the firmware it expects to download. " +
+                    "This is important, since the administrator may change the firmware assignment while device is downloading the firmware. \n\n" +
+                    "Optional 'chunk' and 'size' parameters may be used to download the firmware in chunks. " +
+                    "For example, device may request first 16 KB of firmware using 'chunk'=0 and 'size'=16384. " +
+                    "Next 16KB using 'chunk'=1 and 'size'=16384. The last chunk should have less bytes then requested using 'size' parameter. \n\n" +
+                    REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/firmware", method = RequestMethod.GET)
-    public DeferredResult<ResponseEntity> getFirmware(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> getFirmware(
-                                                      @RequestParam(value = "title") String title,
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
-                                                      @RequestParam(value = "version") String version,
+            @PathVariable("deviceToken") String deviceToken,
-                                                      @RequestParam(value = "size", required = false, defaultValue = "0") int size,
+            @ApiParam(value = "Title of the firmware, corresponds to the value of 'fw_title' attribute.", required = true)
-                                                      @RequestParam(value = "chunk", required = false, defaultValue = "0") int chunk) {
+            @RequestParam(value = "title") String title,
+            @ApiParam(value = "Version of the firmware, corresponds to the value of 'fw_version' attribute.", required = true)
+            @RequestParam(value = "version") String version,
+            @ApiParam(value = "Size of the chunk. Optional. Omit to download the entire file without chunks.")
+            @RequestParam(value = "size", required = false, defaultValue = "0") int size,
+            @ApiParam(value = "Index of the chunk. Optional. Omit to download the entire file without chunks.")
+            @RequestParam(value = "chunk", required = false, defaultValue = "0") int chunk) {
         return getOtaPackageCallback(deviceToken, title, version, size, chunk, OtaPackageType.FIRMWARE);
     }
 
+    @ApiOperation(value = "Get Device Software (getSoftware)",
+            notes = "Downloads the current software package." +
+                    "When the platform initiates software update, " +
+                    "it informs the device by updating the 'sw_title', 'sw_version', 'sw_checksum' and 'sw_checksum_algorithm' shared attributes." +
+                    "The 'sw_title' and 'sw_version' parameters must be supplied in this request to double-check " +
+                    "that the software that device is downloading matches the software it expects to download. " +
+                    "This is important, since the administrator may change the software assignment while device is downloading the software. \n\n" +
+                    "Optional 'chunk' and 'size' parameters may be used to download the software in chunks. " +
+                    "For example, device may request first 16 KB of software using 'chunk'=0 and 'size'=16384. " +
+                    "Next 16KB using 'chunk'=1 and 'size'=16384. The last chunk should have less bytes then requested using 'size' parameter. \n\n" +
+                    REQUIRE_ACCESS_TOKEN,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/{deviceToken}/software", method = RequestMethod.GET)
-    public DeferredResult<ResponseEntity> getSoftware(@PathVariable("deviceToken") String deviceToken,
+    public DeferredResult<ResponseEntity> getSoftware(
-                                                      @RequestParam(value = "title") String title,
+            @ApiParam(value = ACCESS_TOKEN_PARAM_DESCRIPTION, required = true, defaultValue = "YOUR_DEVICE_ACCESS_TOKEN")
-                                                      @RequestParam(value = "version") String version,
+            @PathVariable("deviceToken") String deviceToken,
-                                                      @RequestParam(value = "size", required = false, defaultValue = "0") int size,
+            @ApiParam(value = "Title of the software, corresponds to the value of 'sw_title' attribute.", required = true)
-                                                      @RequestParam(value = "chunk", required = false, defaultValue = "0") int chunk) {
+            @RequestParam(value = "title") String title,
+            @ApiParam(value = "Version of the software, corresponds to the value of 'sw_version' attribute.", required = true)
+            @RequestParam(value = "version") String version,
+            @ApiParam(value = "Size of the chunk. Optional. Omit to download the entire file without using  chunks.")
+            @RequestParam(value = "size", required = false, defaultValue = "0") int size,
+            @ApiParam(value = "Index of the chunk. Optional. Omit to download the entire file without using chunks.")
+            @RequestParam(value = "chunk", required = false, defaultValue = "0") int chunk) {
         return getOtaPackageCallback(deviceToken, title, version, size, chunk, OtaPackageType.SOFTWARE);
     }
 
+    @ApiOperation(value = "Provision new device (provisionDevice)",
+            notes = "Exchange the provision request to the device credentials. " +
+                    "See more info about provisioning in the corresponding 'Device provisioning' platform documentation." +
+                    "Requires valid JSON request with the following format: " +
+                    MARKDOWN_CODE_BLOCK_START +
+                    "{\n" +
+                    "  \"deviceName\": \"NEW_DEVICE_NAME\",\n" +
+                    "  \"provisionDeviceKey\": \"u7piawkboq8v32dmcmpp\",\n" +
+                    "  \"provisionDeviceSecret\": \"jpmwdn8ptlswmf4m29bw\"\n" +
+                    "}" +
+                    MARKDOWN_CODE_BLOCK_END +
+                    "Where 'deviceName' is the name of enw or existing device which depends on the provisioning strategy. " +
+                    "The 'provisionDeviceKey' and 'provisionDeviceSecret' matches info configured in one of the existing device profiles. " +
+                    "The result of the successful call is the JSON object that contains new credentials:" +
+                    MARKDOWN_CODE_BLOCK_START + "{\n" +
+                    "  \"credentialsType\":\"ACCESS_TOKEN\",\n" +
+                    "  \"credentialsValue\":\"DEVICE_ACCESS_TOKEN\",\n" +
+                    "  \"status\":\"SUCCESS\"\n" +
+                    "}" + MARKDOWN_CODE_BLOCK_END
+            ,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/provision", method = RequestMethod.POST)
-    public DeferredResult<ResponseEntity> provisionDevice(@RequestBody String json, HttpServletRequest httpRequest) {
+    public DeferredResult<ResponseEntity> provisionDevice(
+            @ApiParam(value = "JSON with provision request. See API call description for example.")
+            @RequestBody String json) {
         DeferredResult<ResponseEntity> responseWriter = new DeferredResult<>();
         transportContext.getTransportService().process(JsonConverter.convertToProvisionRequestMsg(json),
                 new DeviceProvisionCallback(responseWriter));