Customer Controller API description

Andrii Shvaika
1 parent d6370ed6
Showing 3 changed files with 61 additions and 19 deletions
application/src/main/java/org/thingsboard/server/controller/BaseController.java
application/src/main/java/org/thingsboard/server/controller/CustomerController.java
application/src/main/java/org/thingsboard/server/controller/DeviceController.java
--- a/application/src/main/java/org/thingsboard/server/controller/BaseController.java
View file @bf56d9e
+++ b/application/src/main/java/org/thingsboard/server/controller/BaseController.java
View file @bf56d9e
@@ -166,13 +166,13 @@ public abstract class BaseController {
     protected final String PAGE_SIZE_DESCRIPTION = "Maximum amount of entities in a one page";
     protected final String PAGE_NUMBER_DESCRIPTION = "Sequence number of page starting from 0";
     protected final String DEVICE_TYPE_DESCRIPTION = "Device type as the name of the device profile";
-    protected final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The search is performed by device special field 'textSearch' represented by device name";
+    protected final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device name.";
+    protected final String CUSTOMER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the customer name.";
     protected final String SORT_PROPERTY_DESCRIPTION = "Property of device to sort by";
     protected final String SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, label, type";
     protected final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESCENDING (DESC)";
     protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
-    protected final String DEVICE_INFO_DESCRIPTION = "Device Info is an object which are an extension of default Device object. " +
-            "Apart from Device object, Device Info provides additional information such as customer name and device profile name. ";
+    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. ";
--- a/application/src/main/java/org/thingsboard/server/controller/CustomerController.java
View file @bf56d9e
+++ b/application/src/main/java/org/thingsboard/server/controller/CustomerController.java
View file @bf56d9e
@@ -18,6 +18,8 @@ package org.thingsboard.server.controller;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.node.ObjectNode;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import org.springframework.http.HttpStatus;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -52,16 +54,22 @@ public class CustomerController extends BaseController {
     public static final String CUSTOMER_ID = "customerId";
     public static final String IS_PUBLIC = "isPublic";
+    public static final String CUSTOMER_SECURITY_CHECK = "If the user has the authority of 'Tenant Administrator', the server checks that the customer is owned by the same tenant. " +
+            "If the user has the authority of 'Customer User', the server checks that the user belongs to the customer.";
+    @ApiOperation(value = "Get Customer (getCustomerById)",
+            notes = "Get the Customer object based on the provided Customer Id. " + CUSTOMER_SECURITY_CHECK)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/customer/{customerId}", method = RequestMethod.GET)
     @ResponseBody
-    public Customer getCustomerById(@PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
+    public Customer getCustomerById(
+            @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
+            @PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
         checkParameter(CUSTOMER_ID, strCustomerId);
         try {
             CustomerId customerId = new CustomerId(toUUID(strCustomerId));
             Customer customer = checkCustomerId(customerId, Operation.READ);
-            if(!customer.getAdditionalInfo().isNull()) {
+            if (!customer.getAdditionalInfo().isNull()) {
                 processDashboardIdFromAdditionalInfo((ObjectNode) customer.getAdditionalInfo(), HOME_DASHBOARD);
             }
             return customer;
@@ -70,10 +78,15 @@ public class CustomerController extends BaseController {
         }
     }
+
+    @ApiOperation(value = "Get short Customer info (getShortCustomerInfoById)",
+            notes = "Get the short customer object that contains only the title and 'isPublic' flag. " + CUSTOMER_SECURITY_CHECK)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/customer/{customerId}/shortInfo", method = RequestMethod.GET)
     @ResponseBody
-    public JsonNode getShortCustomerInfoById(@PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
+    public JsonNode getShortCustomerInfoById(
+            @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
+            @PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
         checkParameter(CUSTOMER_ID, strCustomerId);
         try {
             CustomerId customerId = new CustomerId(toUUID(strCustomerId));
@@ -88,10 +101,14 @@ public class CustomerController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Customer Title (getCustomerTitleById)",
+            notes = "Get the title of the customer. " + CUSTOMER_SECURITY_CHECK)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/customer/{customerId}/title", method = RequestMethod.GET, produces = "application/text")
     @ResponseBody
-    public String getCustomerTitleById(@PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
+    public String getCustomerTitleById(
+            @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
+            @PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
         checkParameter(CUSTOMER_ID, strCustomerId);
         try {
             CustomerId customerId = new CustomerId(toUUID(strCustomerId));
@@ -102,10 +119,14 @@ public class CustomerController extends BaseController {
         }
     }
+    @ApiOperation(value = "Create or update Customer (saveCustomer)",
+            notes = "Creates or Updates the Customer. Platform generates random Customer Id during device creation. " +
+                    "The Customer Id will be present in the response. Specify the Customer Id when you would like to update the Customer. " +
+                    "Referencing non-existing Customer Id will cause an error.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/customer", method = RequestMethod.POST)
     @ResponseBody
-    public Customer saveCustomer(@RequestBody Customer customer) throws ThingsboardException {
+    public Customer saveCustomer(@ApiParam(value = "A JSON value representing the customer.") @RequestBody Customer customer) throws ThingsboardException {
         try {
             customer.setTenantId(getCurrentUser().getTenantId());
@@ -131,10 +152,13 @@ public class CustomerController extends BaseController {
         }
     }
+    @ApiOperation(value = "Delete Customer (deleteCustomer)",
+            notes = "Deletes the Customer and all customer Users. All assigned Dashboards, Assets, Devices, etc. will be unassigned but not deleted. Referencing non-existing Customer Id will cause an error.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/customer/{customerId}", method = RequestMethod.DELETE)
     @ResponseStatus(value = HttpStatus.OK)
-    public void deleteCustomer(@PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
+    public void deleteCustomer(@ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
+                               @PathVariable(CUSTOMER_ID) String strCustomerId) throws ThingsboardException {
         checkParameter(CUSTOMER_ID, strCustomerId);
         try {
             CustomerId customerId = new CustomerId(toUUID(strCustomerId));
@@ -161,14 +185,23 @@ public class CustomerController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Tenant Customers (getCustomers)",
+            notes = "Returns a page of customers owned by tenant. " +
+                    PAGE_DATA_PARAMETERS)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/customers", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
-    public PageData<Customer> getCustomers(@RequestParam int pageSize,
-                                           @RequestParam int page,
-                                           @RequestParam(required = false) String textSearch,
-                                           @RequestParam(required = false) String sortProperty,
-                                           @RequestParam(required = false) String sortOrder) throws ThingsboardException {
+    public PageData<Customer> getCustomers(
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION)
+            @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
+            @RequestParam int page,
+            @ApiParam(value = CUSTOMER_TEXT_SEARCH_DESCRIPTION)
+            @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = SORT_PROPERTY_ALLOWABLE_VALUES)
+            @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
+            @RequestParam(required = false) String sortOrder) throws ThingsboardException {
         try {
             PageLink pageLink = createPageLink(pageSize, page, textSearch, sortProperty, sortOrder);
             TenantId tenantId = getCurrentUser().getTenantId();
@@ -178,10 +211,13 @@ public class CustomerController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Tenant Customer by Customer title (getTenantCustomer)",
+            notes = "Get the Customer using Customer Title. Available for users with 'Tenant Administrator' authority only.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/customers", params = {"customerTitle"}, method = RequestMethod.GET)
     @ResponseBody
     public Customer getTenantCustomer(
+            @ApiParam(value = "A string value representing the Customer title.")
             @RequestParam String customerTitle) throws ThingsboardException {
         try {
             TenantId tenantId = getCurrentUser().getTenantId();
--- a/application/src/main/java/org/thingsboard/server/controller/DeviceController.java
View file @bf56d9e
+++ b/application/src/main/java/org/thingsboard/server/controller/DeviceController.java
View file @bf56d9e
@@ -101,7 +101,9 @@ public class DeviceController extends BaseController {
     private final DeviceBulkImportService deviceBulkImportService;
     @ApiOperation(value = "Get Device (getDeviceById)",
-            notes = "If device with given Id exists in the system it will be present in the response, otherwise an empty object will be provided")
+            notes = "Fetch the Device object based on the provided Device Id. " +
+                    "If the user has the authority of 'Tenant Administrator', the server checks that the device is owned by the same tenant. " +
+                    "If the user has the authority of 'Customer User', the server checks that the device is assigned to the same customer.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/device/{deviceId}", method = RequestMethod.GET)
     @ResponseBody
@@ -116,7 +118,10 @@ public class DeviceController extends BaseController {
         }
     }
-    @ApiOperation(value = "Get Device Info (getDeviceInfoById)", notes = DEVICE_INFO_DESCRIPTION)
+    @ApiOperation(value = "Get Device Info (getDeviceInfoById)",
+            notes = "Fetch the Device Info object based on the provided Device Id. " +
+            "If the user has the authority of 'Tenant Administrator', the server checks that the device is owned by the same tenant. " +
+            "If the user has the authority of 'Customer User', the server checks that the device is assigned to the same customer. " + DEVICE_INFO_DESCRIPTION)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/device/info/{deviceId}", method = RequestMethod.GET)
     @ResponseBody
@@ -131,7 +136,8 @@ public class DeviceController extends BaseController {
         }
     }
-    @ApiOperation(value = "Create Or Update Device (saveDevice)", notes = "Platform generates random device Id and credentials (access token) during device creation. " +
+    @ApiOperation(value = "Create Or Update Device (saveDevice)",
+            notes = "Creates or Updates the Device. Platform generates random device Id and credentials (access token) during device creation. " +
             "The device id will be present in the response. " +
             "Specify the device id when you would like to update the device. Referencing non-existing device Id will cause an error.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
@@ -177,7 +183,7 @@ public class DeviceController extends BaseController {
     }
     @ApiOperation(value = "Delete device (deleteDevice)",
-            notes = "Referencing non-existing device Id will cause an error.")
+            notes = "Deletes the device and it's credentials. Referencing non-existing device Id will cause an error.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/device/{deviceId}", method = RequestMethod.DELETE)
     @ResponseStatus(value = HttpStatus.OK)
@@ -361,7 +367,7 @@ public class DeviceController extends BaseController {
         }
     }
-    @ApiOperation(value = "Get Tenant Devices (getEdgeDevices)",
+    @ApiOperation(value = "Get Tenant Devices (getTenantDevices)",
             notes = "Returns a page of devices owned by tenant. " +
                     PAGE_DATA_PARAMETERS)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")