From f12bac3b6c8b36d8e30397419cb1553a3ea01d14 Mon Sep 17 00:00:00 2001 From: Mariesnlk Date: Wed, 6 Oct 2021 17:46:36 +0300 Subject: [PATCH 1/5] add swagger docs to telemetry controller --- .../controller/TelemetryController.java | 125 ++++++++++++------ 1 file changed, 82 insertions(+), 43 deletions(-) diff --git a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java index d311cdbfed..d206fb276c 100644 --- a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java +++ b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java @@ -1,12 +1,12 @@ /** * Copyright © 2016-2021 The Thingsboard Authors - * + *

* Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * + *

+ * http://www.apache.org/licenses/LICENSE-2.0 + *

* Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -26,6 +26,8 @@ import com.google.common.util.concurrent.MoreExecutors; import com.google.gson.JsonElement; import com.google.gson.JsonParseException; import com.google.gson.JsonParser; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Value; @@ -133,83 +135,101 @@ public class TelemetryController extends BaseController { } } + @ApiOperation(value = "Get all existed attributes of entity by it`s type", + notes = "Returns key`s name of the attribute") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeys( - @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr) throws ThingsboardException { + @ApiParam(value = "A string value representing the entity type. For example, 'ASSET'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id of the required entity type. For example, '87b2fe90-2050-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, this::getAttributeKeysCallback); } + @ApiOperation(value = "Get all existed attributes of entity by type and scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeysByScope( - @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr - , @PathVariable("scope") String scope) throws ThingsboardException { + @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the scope. For example, 'SERVER_SCOPE'. In the result will be return all server attributes") @PathVariable("scope") String scope) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeKeysCallback(result, tenantId, entityId, scope)); } + @ApiOperation(value = "Get all existed attributes of entity by it`s type", + notes = "Returns key and value of the attribute") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributes( - @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { + @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, null, keysStr)); } + @ApiOperation(value = "Get all existed attributes of entity by it`s type and scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributesByScope( - @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @PathVariable("scope") String scope, - @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { + @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the entity type. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, + @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, scope, keysStr)); } + @ApiOperation(value = "Get all timeseries keys of entity", + notes = "Return all keys of timeseries of entity id and type") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getTimeseriesKeys( - @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr) throws ThingsboardException { + @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> Futures.addCallback(tsService.findAllLatest(tenantId, entityId), getTsKeysToResponseCallback(result), MoreExecutors.directExecutor())); } + @ApiOperation(value = "Get all last timeseries of entity", + notes = "Return all last timeserie(last time updated or created) of entity id and type") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getLatestTimeseries( - @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @RequestParam(name = "keys", required = false) String keysStr, - @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { + @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys", required = false) String keysStr, + @ApiParam(value = "A boolean value representing if value of timeseries is representing as a string (by default) or as original type") @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> getLatestTimeseriesValuesCallback(result, user, entityId, keysStr, useStrictDataTypes)); } - + @ApiOperation(value = "Get all last timeseries of entity", + notes = "Return all timeseries of entity in selected period of time. Based on this information can be built " + + "widget on the dashboard to see updated telemetry in real-time") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET, params = {"keys", "startTs", "endTs"}) @ResponseBody public DeferredResult getTimeseries( - @PathVariable("entityType") String entityType, - @PathVariable("entityId") String entityIdStr, - @RequestParam(name = "keys") String keys, - @RequestParam(name = "startTs") Long startTs, - @RequestParam(name = "endTs") Long endTs, - @RequestParam(name = "interval", defaultValue = "0") Long interval, + @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys") String keys, + @ApiParam(value = "A string value representing the start point of time") @RequestParam(name = "startTs") Long startTs, + @ApiParam(value = "A string value representing the end point of time") @RequestParam(name = "endTs") Long endTs, + @ApiParam(value = "A long value representing the period of time") @RequestParam(name = "interval", defaultValue = "0") Long interval, @RequestParam(name = "limit", defaultValue = "100") Integer limit, - @RequestParam(name = "agg", defaultValue = "NONE") String aggStr, - @RequestParam(name = "orderBy", defaultValue = "DESC") String orderBy, + @ApiParam(value = "A string value representing the function. For example, 'AVG'") @RequestParam(name = "agg", defaultValue = "NONE") String aggStr, + @ApiParam(value = "A string value representing a sorting type") @RequestParam(name = "orderBy", defaultValue = "DESC") String orderBy, @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> { @@ -222,25 +242,33 @@ public class TelemetryController extends BaseController { }); } + @ApiOperation(value = "Create and save attribute of device") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.POST) @ResponseBody - public DeferredResult saveDeviceAttributes(@PathVariable("deviceId") String deviceIdStr, @PathVariable("scope") String scope, - @RequestBody JsonNode request) throws ThingsboardException { + public DeferredResult saveDeviceAttributes( + @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("deviceId") String deviceIdStr, + @ApiParam(value = "A string value representing the entity type. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, + @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndUuid(EntityType.DEVICE, deviceIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } + @ApiOperation(value = "Create and save attribute of entity") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.POST) @ResponseBody - public DeferredResult saveEntityAttributesV1(@PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @PathVariable("scope") String scope, - @RequestBody JsonNode request) throws ThingsboardException { + public DeferredResult saveEntityAttributesV1( + @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the entity id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the entity type. For example, 'SHARED_SCOPE'") @PathVariable("scope") String scope, + @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } + @ApiOperation(value = "Create and save attribute of entity", + notes = "The same as saveEntityAttributesV1") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/attributes/{scope}", method = RequestMethod.POST) @ResponseBody @@ -251,35 +279,47 @@ public class TelemetryController extends BaseController { return saveAttributes(getTenantId(), entityId, scope, request); } + @ApiOperation(value = "Save telemetry of entity type and scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}", method = RequestMethod.POST) @ResponseBody - public DeferredResult saveEntityTelemetry(@PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @PathVariable("scope") String scope, - @RequestBody String requestBody) throws ThingsboardException { + public DeferredResult saveEntityTelemetry( + @ApiParam(value = "A string value representing the device type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the scope. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, + @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveTelemetry(getTenantId(), entityId, requestBody, 0L); } + @ApiOperation(value = "Save telemetry of entity type and scope", + notes = "The TTL parameter is used to extract the number of days to store the data.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}/{ttl}", method = RequestMethod.POST) @ResponseBody - public DeferredResult saveEntityTelemetryWithTTL(@PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @PathVariable("scope") String scope, @PathVariable("ttl") Long ttl, - @RequestBody String requestBody) throws ThingsboardException { + public DeferredResult saveEntityTelemetryWithTTL( + @ApiParam(value = "A string value representing the device type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the scope. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, + @ApiParam(value = "A long value representing the amount of days.") @PathVariable("ttl") Long ttl, + @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveTelemetry(getTenantId(), entityId, requestBody, ttl); } + @ApiOperation(value = "Delete entity timeseries", + notes = "Delete all timeseries of entity in the required period of time") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/delete", method = RequestMethod.DELETE) @ResponseBody - public DeferredResult deleteEntityTimeseries(@PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @RequestParam(name = "keys") String keysStr, - @RequestParam(name = "deleteAllDataForKeys", defaultValue = "false") boolean deleteAllDataForKeys, - @RequestParam(name = "startTs", required = false) Long startTs, - @RequestParam(name = "endTs", required = false) Long endTs, - @RequestParam(name = "rewriteLatestIfDeleted", defaultValue = "false") boolean rewriteLatestIfDeleted) throws ThingsboardException { + public DeferredResult deleteEntityTimeseries( + @ApiParam(value = "A string value representing the device type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, + @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, + @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys") String keysStr, + @ApiParam(value = "A boolean value representing if should be deleted all data of required key or only the latest") @RequestParam(name = "deleteAllDataForKeys", defaultValue = "false") boolean deleteAllDataForKeys, + @ApiParam(value = "A long value representing the start point of time") @RequestParam(name = "startTs", required = false) Long startTs, + @ApiParam(value = "A long value representing the end point of time") @RequestParam(name = "endTs", required = false) Long endTs, + @RequestParam(name = "rewriteLatestIfDeleted", defaultValue = "false") boolean rewriteLatestIfDeleted) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return deleteTimeseries(entityId, keysStr, deleteAllDataForKeys, startTs, endTs, rewriteLatestIfDeleted); } @@ -311,7 +351,6 @@ public class TelemetryController extends BaseController { for (String key : keys) { deleteTsKvQueries.add(new BaseDeleteTsKvQuery(key, deleteFromTs, deleteToTs, rewriteLatestIfDeleted)); } - ListenableFuture> future = tsService.remove(user.getTenantId(), entityId, deleteTsKvQueries); Futures.addCallback(future, new FutureCallback>() { @Override From 28a2b11faa299e899a244c1d3032fc6d31b28418 Mon Sep 17 00:00:00 2001 From: Mariesnlk Date: Thu, 7 Oct 2021 15:29:37 +0300 Subject: [PATCH 2/5] fix license in telemetry controller --- .../server/controller/TelemetryController.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java index d206fb276c..8e3f5c16a7 100644 --- a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java +++ b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java @@ -1,12 +1,12 @@ /** * Copyright © 2016-2021 The Thingsboard Authors - *

+ * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - *

- * http://www.apache.org/licenses/LICENSE-2.0 - *

+ * + * http://www.apache.org/licenses/LICENSE-2.0 + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. From da36801789ab0df248391ba9e9f52002e7b7739c Mon Sep 17 00:00:00 2001 From: Mariesnlk Date: Mon, 11 Oct 2021 12:53:47 +0300 Subject: [PATCH 3/5] fix swagger in telemetry controller after review --- .../controller/TelemetryController.java | 145 ++++++++++-------- 1 file changed, 79 insertions(+), 66 deletions(-) diff --git a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java index 8e3f5c16a7..051c19c0a4 100644 --- a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java +++ b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java @@ -50,7 +50,6 @@ import org.thingsboard.server.common.data.EntityType; import org.thingsboard.server.common.data.TenantProfile; import org.thingsboard.server.common.data.audit.ActionType; import org.thingsboard.server.common.data.exception.ThingsboardException; -import org.thingsboard.server.common.data.id.CustomerId; import org.thingsboard.server.common.data.id.DeviceId; import org.thingsboard.server.common.data.id.EntityId; import org.thingsboard.server.common.data.id.EntityIdFactory; @@ -110,6 +109,14 @@ import java.util.stream.Collectors; @Slf4j public class TelemetryController extends BaseController { + public static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'"; + public static final String ENTITY_SCOPE_DESCRIPTION = "A string value representing the entity scope. Required values: 'SERVER_SCOPE', 'CLIENT_SCOPE' or 'SHARED_SCOPE'. For example, 'SERVER_SCOPE'."; + public static final String ENTITY_ID_DESCRIPTION = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'"; + public static final String ENTITY_TIMESERIES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of timeseries keys. If keys are not selected, the result will return all the latest timeseries. For example, 'active,inactivityAlarmTime'"; + public static final String ENTITY_ATTRIBUTES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of attributes keys. If keys are not selected, the result will return all the latest timeseries. For example, 'active,inactivityAlarmTime'"; + public static final String ENTITY_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}'"; + public static final String DEVICE_ID_DESCRIPTION = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'"; + @Autowired private TimeseriesService tsService; @@ -135,101 +142,101 @@ public class TelemetryController extends BaseController { } } - @ApiOperation(value = "Get all existed attributes of entity by it`s type", - notes = "Returns key`s name of the attribute") + @ApiOperation(value = "Get all attributes for selected entity", + notes = "Returns key names for the selected entity id and type") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeys( @ApiParam(value = "A string value representing the entity type. For example, 'ASSET'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id of the required entity type. For example, '87b2fe90-2050-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr) throws ThingsboardException { + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, this::getAttributeKeysCallback); } - @ApiOperation(value = "Get all existed attributes of entity by type and scope") + @ApiOperation(value = "Get all attributes for selected entity by attributes scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeysByScope( - @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the scope. For example, 'SERVER_SCOPE'. In the result will be return all server attributes") @PathVariable("scope") String scope) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION + " In the result will be return all server attributes") @PathVariable("scope") String scope) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeKeysCallback(result, tenantId, entityId, scope)); } - @ApiOperation(value = "Get all existed attributes of entity by it`s type", + @ApiOperation(value = "Get all attributes for selected entity id and type", notes = "Returns key and value of the attribute") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributes( - @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, null, keysStr)); } - @ApiOperation(value = "Get all existed attributes of entity by it`s type and scope") + @ApiOperation(value = "Get all attributes for selected entity id, type and scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributesByScope( - @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the entity type. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, - @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, scope, keysStr)); } - @ApiOperation(value = "Get all timeseries keys of entity", - notes = "Return all keys of timeseries of entity id and type") + @ApiOperation(value = "Get all timeseries keys for selected entity id and type") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getTimeseriesKeys( - @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> Futures.addCallback(tsService.findAllLatest(tenantId, entityId), getTsKeysToResponseCallback(result), MoreExecutors.directExecutor())); } - @ApiOperation(value = "Get all last timeseries of entity", - notes = "Return all last timeserie(last time updated or created) of entity id and type") + @ApiOperation(value = "Get all last timeseries for selected entity id and type", + notes = "Return all last timeserie(last time updated or created) for selected entity id and type") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getLatestTimeseries( - @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys", required = false) String keysStr, - @ApiParam(value = "A boolean value representing if value of timeseries is representing as a string (by default) or as original type") @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr, + @ApiParam(value = "A boolean value to specify if values of specified timeseries keys will representing a string (by default) or use strict data type.") @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> getLatestTimeseriesValuesCallback(result, user, entityId, keysStr, useStrictDataTypes)); } - @ApiOperation(value = "Get all last timeseries of entity", - notes = "Return all timeseries of entity in selected period of time. Based on this information can be built " + + @ApiOperation(value = "Get all timeseries for selected entity", + notes = "Return all timeseries for selected entity id, type and period of time. Based on this information can be built " + "widget on the dashboard to see updated telemetry in real-time") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET, params = {"keys", "startTs", "endTs"}) @ResponseBody public DeferredResult getTimeseries( - @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys") String keys, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keys, @ApiParam(value = "A string value representing the start point of time") @RequestParam(name = "startTs") Long startTs, @ApiParam(value = "A string value representing the end point of time") @RequestParam(name = "endTs") Long endTs, @ApiParam(value = "A long value representing the period of time") @RequestParam(name = "interval", defaultValue = "0") Long interval, @RequestParam(name = "limit", defaultValue = "100") Integer limit, - @ApiParam(value = "A string value representing the function. For example, 'AVG'") @RequestParam(name = "agg", defaultValue = "NONE") String aggStr, - @ApiParam(value = "A string value representing a sorting type") @RequestParam(name = "orderBy", defaultValue = "DESC") String orderBy, + @ApiParam(value = "A string value representing the function. Available parameters: 'MIN', 'MAX', 'AVG', 'SUM', 'COUNT', 'NONE'." + + " If the interval is 0, aggStr will be converted to 'NONE' value. For example, 'AVG'") @RequestParam(name = "agg", defaultValue = "NONE") String aggStr, + @ApiParam(value = "A string value representing a sorting type. Available values 'DESC' or 'ASC'") @RequestParam(name = "orderBy", defaultValue = "DESC") String orderBy, @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> { @@ -242,33 +249,33 @@ public class TelemetryController extends BaseController { }); } - @ApiOperation(value = "Create and save attribute of device") + @ApiOperation(value = "Create and save attribute for selected device") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveDeviceAttributes( - @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("deviceId") String deviceIdStr, - @ApiParam(value = "A string value representing the entity type. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, - @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody JsonNode request) throws ThingsboardException { + @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndUuid(EntityType.DEVICE, deviceIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Create and save attribute of entity") + @ApiOperation(value = "Create and save attribute for selected entity") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityAttributesV1( - @ApiParam(value = "A string value representing the entity type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the entity id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the entity type. For example, 'SHARED_SCOPE'") @PathVariable("scope") String scope, - @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody JsonNode request) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Create and save attribute of entity", - notes = "The same as saveEntityAttributesV1") + @ApiOperation(value = "Create and save attribute for selected entity", + notes = "The same as saveEntityAttributesV1") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/attributes/{scope}", method = RequestMethod.POST) @ResponseBody @@ -279,44 +286,44 @@ public class TelemetryController extends BaseController { return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Save telemetry of entity type and scope") + @ApiOperation(value = "Save telemetry for selected entity id, type and scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityTelemetry( - @ApiParam(value = "A string value representing the device type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the scope. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, - @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody String requestBody) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveTelemetry(getTenantId(), entityId, requestBody, 0L); } - @ApiOperation(value = "Save telemetry of entity type and scope", + @ApiOperation(value = "Save telemetry for selected entity id, type and scope", notes = "The TTL parameter is used to extract the number of days to store the data.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}/{ttl}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityTelemetryWithTTL( - @ApiParam(value = "A string value representing the device type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the scope. For example, 'SERVER_SCOPE'") @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = "A long value representing the amount of days.") @PathVariable("ttl") Long ttl, - @ApiParam(value = "A string value representing the json object. Should contains key and value of the attribute. For example, '{\"key\":\"value\"}'") @RequestBody String requestBody) throws ThingsboardException { + @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveTelemetry(getTenantId(), entityId, requestBody, ttl); } @ApiOperation(value = "Delete entity timeseries", - notes = "Delete all timeseries of entity in the required period of time") + notes = "Delete all timeseries for selected entity in the required period of time") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/delete", method = RequestMethod.DELETE) @ResponseBody public DeferredResult deleteEntityTimeseries( - @ApiParam(value = "A string value representing the device type. For example, 'DEVICE'") @PathVariable("entityType") String entityType, - @ApiParam(value = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'") @PathVariable("entityId") String entityIdStr, - @ApiParam(value = "A string value representing the entity keys. They are optional and listed with comma with no space between keys. For example, 'active,inactivityAlarmTime'") @RequestParam(name = "keys") String keysStr, - @ApiParam(value = "A boolean value representing if should be deleted all data of required key or only the latest") @RequestParam(name = "deleteAllDataForKeys", defaultValue = "false") boolean deleteAllDataForKeys, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr, + @ApiParam(value = "A boolean value representing if should be deleted all data of required keys or only the latest") @RequestParam(name = "deleteAllDataForKeys", defaultValue = "false") boolean deleteAllDataForKeys, @ApiParam(value = "A long value representing the start point of time") @RequestParam(name = "startTs", required = false) Long startTs, @ApiParam(value = "A long value representing the end point of time") @RequestParam(name = "endTs", required = false) Long endTs, @RequestParam(name = "rewriteLatestIfDeleted", defaultValue = "false") boolean rewriteLatestIfDeleted) throws ThingsboardException { @@ -368,22 +375,28 @@ public class TelemetryController extends BaseController { }); } + @ApiOperation(value = "Delete entity attributes", + notes = "Delete entity attributes for selected device id and scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.DELETE) @ResponseBody - public DeferredResult deleteEntityAttributes(@PathVariable("deviceId") String deviceIdStr, - @PathVariable("scope") String scope, - @RequestParam(name = "keys") String keysStr) throws ThingsboardException { + public DeferredResult deleteEntityAttributes( + @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndUuid(EntityType.DEVICE, deviceIdStr); return deleteAttributes(entityId, scope, keysStr); } + @ApiOperation(value = "Delete entity attributes", + notes = "Delete entity attributes for selected entity id and scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.DELETE) @ResponseBody - public DeferredResult deleteEntityAttributes(@PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @PathVariable("scope") String scope, - @RequestParam(name = "keys") String keysStr) throws ThingsboardException { + public DeferredResult deleteEntityAttributes( + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return deleteAttributes(entityId, scope, keysStr); } From 9534bf311e8796547f6e197171e4f920e0d49e76 Mon Sep 17 00:00:00 2001 From: Mariesnlk Date: Mon, 11 Oct 2021 16:28:11 +0300 Subject: [PATCH 4/5] fix swagger docs after riview --- .../server/controller/BaseController.java | 1 + .../server/controller/DeviceController.java | 2 +- .../controller/TelemetryController.java | 101 ++++++++++-------- 3 files changed, 56 insertions(+), 48 deletions(-) diff --git a/application/src/main/java/org/thingsboard/server/controller/BaseController.java b/application/src/main/java/org/thingsboard/server/controller/BaseController.java index f320b8eafa..8c0c63508d 100644 --- a/application/src/main/java/org/thingsboard/server/controller/BaseController.java +++ b/application/src/main/java/org/thingsboard/server/controller/BaseController.java @@ -156,6 +156,7 @@ public abstract class BaseController { public static final String INCORRECT_TENANT_ID = "Incorrect tenantId "; protected static final String DEFAULT_DASHBOARD = "defaultDashboardId"; protected static final String HOME_DASHBOARD = "homeDashboardId"; + public static final String DEVICE_ID_DESCRIPTION = "A string value representing the device id."; private static final int DEFAULT_PAGE_SIZE = 1000; diff --git a/application/src/main/java/org/thingsboard/server/controller/DeviceController.java b/application/src/main/java/org/thingsboard/server/controller/DeviceController.java index 2bb23ccae7..0cb1327f01 100644 --- a/application/src/main/java/org/thingsboard/server/controller/DeviceController.java +++ b/application/src/main/java/org/thingsboard/server/controller/DeviceController.java @@ -97,7 +97,7 @@ import static org.thingsboard.server.controller.EdgeController.EDGE_ID; @RequiredArgsConstructor @Slf4j public class DeviceController extends BaseController { - 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_ID_PARAM_DESCRIPTION = BaseController.DEVICE_ID_DESCRIPTION + " For example, '784f394c-42b6-435a-983c-b7beff2784f9'"; private final DeviceBulkImportService deviceBulkImportService; private static final String DEVICE_ID = "deviceId"; diff --git a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java index 051c19c0a4..f41ec2661a 100644 --- a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java +++ b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java @@ -109,13 +109,17 @@ import java.util.stream.Collectors; @Slf4j public class TelemetryController extends BaseController { - public static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'"; - public static final String ENTITY_SCOPE_DESCRIPTION = "A string value representing the entity scope. Required values: 'SERVER_SCOPE', 'CLIENT_SCOPE' or 'SHARED_SCOPE'. For example, 'SERVER_SCOPE'."; + public static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type."; + public static final String DEVICE_ENTITY_TYPE_DESCRIPTION = ENTITY_TYPE_DESCRIPTION + " For example, 'DEVICE'"; + public static final String ASSET_ENTITY_TYPE_DESCRIPTION = ENTITY_TYPE_DESCRIPTION + " For example, 'ASSET'"; + public static final String ATTRIBUTES_SCOPE_DESCRIPTION = "A string value representing the attributes scope. Allowed values: 'SERVER_SCOPE', 'CLIENT_SCOPE' or 'SHARED_SCOPE'. "; + public static final String CLIENT_SCOPE_DESCRIPTION = ATTRIBUTES_SCOPE_DESCRIPTION + " For example, 'CLIENT_SCOPE'."; + public static final String SERVER_SCOPE_DESCRIPTION = ATTRIBUTES_SCOPE_DESCRIPTION + " For example, 'SERVER_SCOPE'."; public static final String ENTITY_ID_DESCRIPTION = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'"; - public static final String ENTITY_TIMESERIES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of timeseries keys. If keys are not selected, the result will return all the latest timeseries. For example, 'active,inactivityAlarmTime'"; - public static final String ENTITY_ATTRIBUTES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of attributes keys. If keys are not selected, the result will return all the latest timeseries. For example, 'active,inactivityAlarmTime'"; + public static final String ENTITY_TIMESERIES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of timeseries keys. If keys are not selected, the result will return all the latest timeseries. For example, 'temp,humidity'"; + public static final String ENTITY_ATTRIBUTES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of attributes keys. For example, 'active,inactivityAlarmTime'"; public static final String ENTITY_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}'"; - public static final String DEVICE_ID_DESCRIPTION = "A string value representing the device id. For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'"; + public static final String DEVICE_ID_DESCRIPTION = BaseController.DEVICE_ID_DESCRIPTION + "For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'"; @Autowired private TimeseriesService tsService; @@ -142,75 +146,78 @@ public class TelemetryController extends BaseController { } } - @ApiOperation(value = "Get all attributes for selected entity", - notes = "Returns key names for the selected entity id and type") + @ApiOperation(value = "Get all attribute keys for selected entity", + notes = "Returns key names for the selected entity") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeys( - @ApiParam(value = "A string value representing the entity type. For example, 'ASSET'") @PathVariable("entityType") String entityType, + @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, this::getAttributeKeysCallback); } - @ApiOperation(value = "Get all attributes for selected entity by attributes scope") + @ApiOperation(value = "Get all attributes for selected entity by attributes scope", + notes = "Returns key names for the selected entity by attributes scope ") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeysByScope( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION + " In the result will be return all server attributes") @PathVariable("scope") String scope) throws ThingsboardException { + @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION + "For example, 'SERVER_SCOPE'. In the result will be return all server attributes") @PathVariable("scope") String scope) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeKeysCallback(result, tenantId, entityId, scope)); } - @ApiOperation(value = "Get all attributes for selected entity id and type", - notes = "Returns key and value of the attribute") + @ApiOperation(value = "Get all attributes for selected entity", + notes = "Returns keys and values of the attribute for selected entity") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributes( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, null, keysStr)); } - @ApiOperation(value = "Get all attributes for selected entity id, type and scope") + @ApiOperation(value = "Get all attributes for selected entity and attributes scope", + notes = "Returns keys and values of the attribute for selected entity and attributes scope") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributesByScope( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = SERVER_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, scope, keysStr)); } - @ApiOperation(value = "Get all timeseries keys for selected entity id and type") + @ApiOperation(value = "Get all timeseries keys for selected entity", + notes = "Returns keys of the timeseries for selected entity") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getTimeseriesKeys( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> Futures.addCallback(tsService.findAllLatest(tenantId, entityId), getTsKeysToResponseCallback(result), MoreExecutors.directExecutor())); } - @ApiOperation(value = "Get all last timeseries for selected entity id and type", - notes = "Return all last timeserie(last time updated or created) for selected entity id and type") + @ApiOperation(value = "Get all last timeseries for selected entity", + notes = "Return all last timeserie(last time updated or created) for selected entity ") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getLatestTimeseries( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr, @ApiParam(value = "A boolean value to specify if values of specified timeseries keys will representing a string (by default) or use strict data type.") @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { @@ -221,20 +228,20 @@ public class TelemetryController extends BaseController { } @ApiOperation(value = "Get all timeseries for selected entity", - notes = "Return all timeseries for selected entity id, type and period of time. Based on this information can be built " + + notes = "Return all timeseries for selected entity and period of time. Based on this information can be built " + "widget on the dashboard to see updated telemetry in real-time") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET, params = {"keys", "startTs", "endTs"}) @ResponseBody public DeferredResult getTimeseries( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keys, @ApiParam(value = "A string value representing the start point of time") @RequestParam(name = "startTs") Long startTs, @ApiParam(value = "A string value representing the end point of time") @RequestParam(name = "endTs") Long endTs, @ApiParam(value = "A long value representing the period of time") @RequestParam(name = "interval", defaultValue = "0") Long interval, @RequestParam(name = "limit", defaultValue = "100") Integer limit, - @ApiParam(value = "A string value representing the function. Available parameters: 'MIN', 'MAX', 'AVG', 'SUM', 'COUNT', 'NONE'." + + @ApiParam(value = "A string value representing the function. Allowed values: 'MIN', 'MAX', 'AVG', 'SUM', 'COUNT', 'NONE'." + " If the interval is 0, aggStr will be converted to 'NONE' value. For example, 'AVG'") @RequestParam(name = "agg", defaultValue = "NONE") String aggStr, @ApiParam(value = "A string value representing a sorting type. Available values 'DESC' or 'ASC'") @RequestParam(name = "orderBy", defaultValue = "DESC") String orderBy, @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { @@ -249,32 +256,32 @@ public class TelemetryController extends BaseController { }); } - @ApiOperation(value = "Create and save attribute for selected device") + @ApiOperation(value = "Save and update attributes for selected device") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveDeviceAttributes( @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndUuid(EntityType.DEVICE, deviceIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Create and save attribute for selected entity") + @ApiOperation(value = "Save and update attributes for selected entity") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityAttributesV1( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Create and save attribute for selected entity", + @ApiOperation(value = "Save and update attributes for selected entity", notes = "The same as saveEntityAttributesV1") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/attributes/{scope}", method = RequestMethod.POST) @@ -286,28 +293,28 @@ public class TelemetryController extends BaseController { return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Save telemetry for selected entity id, type and scope") + @ApiOperation(value = "Save and update telemetry for selected entity") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityTelemetry( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveTelemetry(getTenantId(), entityId, requestBody, 0L); } - @ApiOperation(value = "Save telemetry for selected entity id, type and scope", + @ApiOperation(value = "Save telemetry for selected entity with ttl", notes = "The TTL parameter is used to extract the number of days to store the data.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}/{ttl}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityTelemetryWithTTL( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = "A long value representing the amount of days.") @PathVariable("ttl") Long ttl, @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); @@ -375,14 +382,14 @@ public class TelemetryController extends BaseController { }); } - @ApiOperation(value = "Delete entity attributes", - notes = "Delete entity attributes for selected device id and scope") + @ApiOperation(value = "Delete device attributes", + notes = "Delete device attributes for selected device") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.DELETE) @ResponseBody public DeferredResult deleteEntityAttributes( @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndUuid(EntityType.DEVICE, deviceIdStr); return deleteAttributes(entityId, scope, keysStr); @@ -394,8 +401,8 @@ public class TelemetryController extends BaseController { @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.DELETE) @ResponseBody public DeferredResult deleteEntityAttributes( - @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, + @ApiParam(value = SERVER_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return deleteAttributes(entityId, scope, keysStr); From b032b5ac39b8e74c93d50c839618938d2bbc4689 Mon Sep 17 00:00:00 2001 From: Mariesnlk Date: Tue, 12 Oct 2021 13:11:24 +0300 Subject: [PATCH 5/5] fix swagger in telemetry controller --- .../server/controller/BaseController.java | 4 +- .../controller/TelemetryController.java | 191 ++++++++++-------- 2 files changed, 104 insertions(+), 91 deletions(-) diff --git a/application/src/main/java/org/thingsboard/server/controller/BaseController.java b/application/src/main/java/org/thingsboard/server/controller/BaseController.java index 833de053fe..fbd1ba6ecf 100644 --- a/application/src/main/java/org/thingsboard/server/controller/BaseController.java +++ b/application/src/main/java/org/thingsboard/server/controller/BaseController.java @@ -174,12 +174,12 @@ public abstract class BaseController { protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC"; protected final String DEVICE_INFO_DESCRIPTION = "Device Info is an extension of the default Device object that contains information about the assigned customer name and device profile name. "; - + protected static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'"; + protected static final String ENTITY_ID_DESCRIPTION = "A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'"; public static final String INCORRECT_TENANT_ID = "Incorrect tenantId "; protected static final String DEFAULT_DASHBOARD = "defaultDashboardId"; protected static final String HOME_DASHBOARD = "homeDashboardId"; - public static final String DEVICE_ID_DESCRIPTION = "A string value representing the device id."; private static final int DEFAULT_PAGE_SIZE = 1000; diff --git a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java index f41ec2661a..60e61a64a1 100644 --- a/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java +++ b/application/src/main/java/org/thingsboard/server/controller/TelemetryController.java @@ -109,17 +109,16 @@ import java.util.stream.Collectors; @Slf4j public class TelemetryController extends BaseController { - public static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type."; - public static final String DEVICE_ENTITY_TYPE_DESCRIPTION = ENTITY_TYPE_DESCRIPTION + " For example, 'DEVICE'"; - public static final String ASSET_ENTITY_TYPE_DESCRIPTION = ENTITY_TYPE_DESCRIPTION + " For example, 'ASSET'"; - public static final String ATTRIBUTES_SCOPE_DESCRIPTION = "A string value representing the attributes scope. Allowed values: 'SERVER_SCOPE', 'CLIENT_SCOPE' or 'SHARED_SCOPE'. "; - public static final String CLIENT_SCOPE_DESCRIPTION = ATTRIBUTES_SCOPE_DESCRIPTION + " For example, 'CLIENT_SCOPE'."; - public static final String SERVER_SCOPE_DESCRIPTION = ATTRIBUTES_SCOPE_DESCRIPTION + " For example, 'SERVER_SCOPE'."; - public static final String ENTITY_ID_DESCRIPTION = "A string value representing the entity id. For example, '16cdaaf0-229d-11ec-b9f0-231c4d2593da'"; - public static final String ENTITY_TIMESERIES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of timeseries keys. If keys are not selected, the result will return all the latest timeseries. For example, 'temp,humidity'"; - public static final String ENTITY_ATTRIBUTES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of attributes keys. For example, 'active,inactivityAlarmTime'"; - public static final String ENTITY_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}'"; - public static final String DEVICE_ID_DESCRIPTION = BaseController.DEVICE_ID_DESCRIPTION + "For example, 'e0034860-2065-11ec-8a0a-15ac1b4580c2'"; + private static final String ATTRIBUTES_SCOPE_DESCRIPTION = "A string value representing the attributes scope. For example, 'SERVER_SCOPE'."; + private static final String ATTRIBUTES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of attributes keys. For example, 'active,inactivityAlarmTime'."; + private static final String ATTRIBUTES_SCOPE_ALLOWED_VALUES = "SERVER_SCOPE, CLIENT_SCOPE, SHARED_SCOPE"; + private static final String ATTRIBUTES_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}'"; + + private static final String TELEMETRY_KEYS_DESCRIPTION = "A string value representing the comma-separated list of timeseries keys. If keys are not selected, the result will return all latest timeseries. For example, 'temp,humidity'."; + private static final String TELEMETRY_SCOPE_DESCRIPTION = "Value is not used in the API call implementation"; + private static final String TELEMETRY_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}' or '{\"ts\":1527863043000,\"values\":{\"key1\":\"value1\",\"key2\":\"value2\"}}'"; + + private static final String STRICT_DATA_TYPES_DESCRIPTION = "A boolean value to specify if values of selected timeseries keys will representing a string (by default) or use strict data type."; @Autowired private TimeseriesService tsService; @@ -146,104 +145,112 @@ public class TelemetryController extends BaseController { } } - @ApiOperation(value = "Get all attribute keys for selected entity", - notes = "Returns key names for the selected entity") + @ApiOperation(value = "Get all attribute keys (getAttributeKeys)", + notes = "Returns key names for the selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeys( - @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, this::getAttributeKeysCallback); } - @ApiOperation(value = "Get all attributes for selected entity by attributes scope", - notes = "Returns key names for the selected entity by attributes scope ") + @ApiOperation(value = "Get all attributes by scope (getAttributeKeysByScope)", + notes = "Returns key names of specified scope for the selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributeKeysByScope( - @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION + "For example, 'SERVER_SCOPE'. In the result will be return all server attributes") @PathVariable("scope") String scope) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION, allowableValues = ATTRIBUTES_SCOPE_ALLOWED_VALUES) @PathVariable("scope") String scope) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeKeysCallback(result, tenantId, entityId, scope)); } - @ApiOperation(value = "Get all attributes for selected entity", - notes = "Returns keys and values of the attribute for selected entity") + @ApiOperation(value = "Get attributes (getAttributes)", + notes = "Returns JSON array of AttributeData objects for the selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributes( - @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, null, keysStr)); } - @ApiOperation(value = "Get all attributes for selected entity and attributes scope", - notes = "Returns keys and values of the attribute for selected entity and attributes scope") + @ApiOperation(value = "Get attributes by scope (getAttributesByScope)", + notes = "Returns JSON array of AttributeData objects for the selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/attributes/{scope}", method = RequestMethod.GET) @ResponseBody public DeferredResult getAttributesByScope( - @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = SERVER_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, - @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION, allowableValues = ATTRIBUTES_SCOPE_ALLOWED_VALUES) @PathVariable("scope") String scope, + @ApiParam(value = ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, (result, tenantId, entityId) -> getAttributeValuesCallback(result, user, entityId, scope, keysStr)); } - @ApiOperation(value = "Get all timeseries keys for selected entity", - notes = "Returns keys of the timeseries for selected entity") + @ApiOperation(value = "Get timeseries keys (getTimeseriesKeys)", + notes = "Returns latest timeseries keys for selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/keys/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getTimeseriesKeys( - @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> Futures.addCallback(tsService.findAllLatest(tenantId, entityId), getTsKeysToResponseCallback(result), MoreExecutors.directExecutor())); } - @ApiOperation(value = "Get all last timeseries for selected entity", - notes = "Return all last timeserie(last time updated or created) for selected entity ") + @ApiOperation(value = "Get latest timeseries (getLatestTimeseries)", + notes = "Returns JSON object with mapping latest timeseries keys to JSON arrays of TsData objects for the selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET) @ResponseBody public DeferredResult getLatestTimeseries( - @ApiParam(value = ASSET_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr, - @ApiParam(value = "A boolean value to specify if values of specified timeseries keys will representing a string (by default) or use strict data type.") @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { + @ApiParam(value = TELEMETRY_KEYS_DESCRIPTION) @RequestParam(name = "keys", required = false) String keysStr, + @ApiParam(value = STRICT_DATA_TYPES_DESCRIPTION) + @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { SecurityUser user = getCurrentUser(); return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> getLatestTimeseriesValuesCallback(result, user, entityId, keysStr, useStrictDataTypes)); } - @ApiOperation(value = "Get all timeseries for selected entity", - notes = "Return all timeseries for selected entity and period of time. Based on this information can be built " + - "widget on the dashboard to see updated telemetry in real-time") + @ApiOperation(value = "Get timeseries (getTimeseries)", + notes = "Returns JSON object with mapping timeseries keys to JSON arrays of TsData objects based on specified filters for the selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET, params = {"keys", "startTs", "endTs"}) @ResponseBody public DeferredResult getTimeseries( - @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keys, - @ApiParam(value = "A string value representing the start point of time") @RequestParam(name = "startTs") Long startTs, - @ApiParam(value = "A string value representing the end point of time") @RequestParam(name = "endTs") Long endTs, - @ApiParam(value = "A long value representing the period of time") @RequestParam(name = "interval", defaultValue = "0") Long interval, + @ApiParam(value = TELEMETRY_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keys, + @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.") + @RequestParam(name = "startTs") Long startTs, + @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.") + @RequestParam(name = "endTs") Long endTs, + @ApiParam(value = "A long value representing the aggregation interval(milliseconds) range.") + @RequestParam(name = "interval", defaultValue = "0") Long interval, + @ApiParam(value = "An integer value representing max number of selected data points.", defaultValue = "100") @RequestParam(name = "limit", defaultValue = "100") Integer limit, - @ApiParam(value = "A string value representing the function. Allowed values: 'MIN', 'MAX', 'AVG', 'SUM', 'COUNT', 'NONE'." + - " If the interval is 0, aggStr will be converted to 'NONE' value. For example, 'AVG'") @RequestParam(name = "agg", defaultValue = "NONE") String aggStr, - @ApiParam(value = "A string value representing a sorting type. Available values 'DESC' or 'ASC'") @RequestParam(name = "orderBy", defaultValue = "DESC") String orderBy, + @ApiParam(value = "A string value representing the aggregation function. " + + "If the interval is not specified, 'agg' parameter will be converted to 'NONE' value.", + allowableValues = "MIN, MAX, AVG, SUM, COUNT, NONE") + @RequestParam(name = "agg", defaultValue = "NONE") String aggStr, + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES) + @RequestParam(name = "orderBy", defaultValue = "DESC") String orderBy, + @ApiParam(value = STRICT_DATA_TYPES_DESCRIPTION) @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException { return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr, (result, tenantId, entityId) -> { @@ -256,83 +263,88 @@ public class TelemetryController extends BaseController { }); } - @ApiOperation(value = "Save and update attributes for selected device") + @ApiOperation(value = "Save or update device attributes (saveDeviceAttributes)") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveDeviceAttributes( - @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, - @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, - @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { + @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION, allowableValues = ATTRIBUTES_SCOPE_ALLOWED_VALUES) @PathVariable("scope") String scope, + @ApiParam(value = ATTRIBUTES_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndUuid(EntityType.DEVICE, deviceIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Save and update attributes for selected entity") + @ApiOperation(value = "Save or update attributes (saveEntityAttributesV1)") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityAttributesV1( - @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, - @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION, allowableValues = ATTRIBUTES_SCOPE_ALLOWED_VALUES) @PathVariable("scope") String scope, + @ApiParam(value = ATTRIBUTES_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Save and update attributes for selected entity", - notes = "The same as saveEntityAttributesV1") + @ApiOperation(value = "Save or update attributes (saveEntityAttributesV2)") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/attributes/{scope}", method = RequestMethod.POST) @ResponseBody - public DeferredResult saveEntityAttributesV2(@PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @PathVariable("scope") String scope, - @RequestBody JsonNode request) throws ThingsboardException { + public DeferredResult saveEntityAttributesV2( + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION, allowableValues = ATTRIBUTES_SCOPE_ALLOWED_VALUES) @PathVariable("scope") String scope, + @ApiParam(value = ATTRIBUTES_JSON_REQUEST_DESCRIPTION) @RequestBody JsonNode request) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveAttributes(getTenantId(), entityId, scope, request); } - @ApiOperation(value = "Save and update telemetry for selected entity") + @ApiOperation(value = "Save or update telemetry (saveEntityTelemetry)") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityTelemetry( - @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, - @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = TELEMETRY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = TELEMETRY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveTelemetry(getTenantId(), entityId, requestBody, 0L); } - @ApiOperation(value = "Save telemetry for selected entity with ttl", + @ApiOperation(value = "Save or update telemetry with TTL (saveEntityTelemetryWithTTL)", notes = "The TTL parameter is used to extract the number of days to store the data.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}/{ttl}", method = RequestMethod.POST) @ResponseBody public DeferredResult saveEntityTelemetryWithTTL( - @ApiParam(value = DEVICE_ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, - @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, - @ApiParam(value = "A long value representing the amount of days.") @PathVariable("ttl") Long ttl, - @ApiParam(value = ENTITY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = TELEMETRY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, + @ApiParam(value = "A long value representing TTL(Time to Live) parameter.") @PathVariable("ttl") Long ttl, + @ApiParam(value = TELEMETRY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return saveTelemetry(getTenantId(), entityId, requestBody, ttl); } - @ApiOperation(value = "Delete entity timeseries", - notes = "Delete all timeseries for selected entity in the required period of time") + @ApiOperation(value = "Delete entity timeseries (deleteEntityTimeseries)", + notes = "Delete timeseries in the specified time range for selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/timeseries/delete", method = RequestMethod.DELETE) @ResponseBody public DeferredResult deleteEntityTimeseries( @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, - @ApiParam(value = ENTITY_TIMESERIES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr, - @ApiParam(value = "A boolean value representing if should be deleted all data of required keys or only the latest") @RequestParam(name = "deleteAllDataForKeys", defaultValue = "false") boolean deleteAllDataForKeys, - @ApiParam(value = "A long value representing the start point of time") @RequestParam(name = "startTs", required = false) Long startTs, - @ApiParam(value = "A long value representing the end point of time") @RequestParam(name = "endTs", required = false) Long endTs, + @ApiParam(value = TELEMETRY_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr, + @ApiParam(value = "A boolean value to specify if should be deleted all data for selected keys or only data that are in the selected time range.") + @RequestParam(name = "deleteAllDataForKeys", defaultValue = "false") boolean deleteAllDataForKeys, + @ApiParam(value = "A long value representing the start timestamp(milliseconds) of removal time range.") + @RequestParam(name = "startTs", required = false) Long startTs, + @ApiParam(value = "A long value representing the end timestamp(milliseconds) of removal time range.") + @RequestParam(name = "endTs", required = false) Long endTs, + @ApiParam(value = "If the parameter is set to true, the latest telemetry will be rewritten if the current latest value was removed, otherwise, the new latest value will not set.") @RequestParam(name = "rewriteLatestIfDeleted", defaultValue = "false") boolean rewriteLatestIfDeleted) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return deleteTimeseries(entityId, keysStr, deleteAllDataForKeys, startTs, endTs, rewriteLatestIfDeleted); @@ -382,28 +394,29 @@ public class TelemetryController extends BaseController { }); } - @ApiOperation(value = "Delete device attributes", - notes = "Delete device attributes for selected device") + @ApiOperation(value = "Delete device attributes (deleteEntityAttributes)", + notes = "Delete attributes of specified scope for selected device.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.DELETE) @ResponseBody public DeferredResult deleteEntityAttributes( - @ApiParam(value = DEVICE_ID_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, - @ApiParam(value = CLIENT_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, - @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { + @ApiParam(value = DEVICE_ID_PARAM_DESCRIPTION) @PathVariable("deviceId") String deviceIdStr, + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION, allowableValues = ATTRIBUTES_SCOPE_ALLOWED_VALUES) @PathVariable("scope") String scope, + @ApiParam(value = ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndUuid(EntityType.DEVICE, deviceIdStr); return deleteAttributes(entityId, scope, keysStr); } - @ApiOperation(value = "Delete entity attributes", - notes = "Delete entity attributes for selected entity id and scope") + @ApiOperation(value = "Delete entity attributes (deleteEntityAttributes)", + notes = "Delete attributes of specified scope for selected entity.") @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.DELETE) @ResponseBody public DeferredResult deleteEntityAttributes( - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, @PathVariable("entityId") String entityIdStr, - @ApiParam(value = SERVER_SCOPE_DESCRIPTION) @PathVariable("scope") String scope, - @ApiParam(value = ENTITY_ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { + @ApiParam(value = ENTITY_TYPE_DESCRIPTION) @PathVariable("entityType") String entityType, + @ApiParam(value = ENTITY_ID_DESCRIPTION) @PathVariable("entityId") String entityIdStr, + @ApiParam(value = ATTRIBUTES_SCOPE_DESCRIPTION, allowableValues = ATTRIBUTES_SCOPE_ALLOWED_VALUES) @PathVariable("scope") String scope, + @ApiParam(value = ATTRIBUTES_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr) throws ThingsboardException { EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr); return deleteAttributes(entityId, scope, keysStr); }