Tenant and Tenant Profile Controllers

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

@@ -169,6 +169,7 @@ public abstract class BaseController {
     public static final String RPC_ID_PARAM_DESCRIPTION = "A string value representing the rpc id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String DEVICE_ID_PARAM_DESCRIPTION = "A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String DEVICE_PROFILE_ID_PARAM_DESCRIPTION = "A string value representing the device profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
+    public static final String TENANT_PROFILE_ID_PARAM_DESCRIPTION = "A string value representing the tenant profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String TENANT_ID_PARAM_DESCRIPTION = "A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String EDGE_ID_PARAM_DESCRIPTION = "A string value representing the edge id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String CUSTOMER_ID_PARAM_DESCRIPTION = "A string value representing the customer id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
@@ -179,6 +180,8 @@ public abstract class BaseController {
     public static final String ENTITY_TYPE_PARAM_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'";
     public static final String RULE_CHAIN_ID_PARAM_DESCRIPTION = "A string value representing the rule chain id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
 
+    protected static final String SYSTEM_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'SYS_ADMIN' authority.";
+    protected static final String SYSTEM_AND_TENANT_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority.";
     protected static final String TENANT_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'TENANT_ADMIN' authority.";
     protected static final String TENANT_AND_USER_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority.";
 
@@ -193,6 +196,8 @@ public abstract class BaseController {
     protected static final String DASHBOARD_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the dashboard title.";
     protected static final String RPC_TEXT_SEARCH_DESCRIPTION = "Not implemented. Leave empty.";
     protected static final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device name.";
+    protected static final String TENANT_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the tenant name.";
+    protected static final String TENANT_PROFILE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the tenant profile name.";
     protected static final String RULE_CHAIN_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the rule chain name.";
     protected static final String DEVICE_PROFILE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device profile name.";
     protected static final String CUSTOMER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the customer title.";
@@ -204,6 +209,10 @@ public abstract class BaseController {
     protected static final String CUSTOMER_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, email, country, city";
     protected static final String RPC_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, expirationTime, request, response";
     protected static final String DEVICE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, deviceProfileName, label, customerTitle";
+    protected static final String TENANT_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, email, country, state, city, address, address2, zip, phone, email";
+    protected static final String TENANT_PROFILE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, description, isDefault";
+    protected static final String TENANT_PROFILE_INFO_SORT_PROPERTY_ALLOWABLE_VALUES = "id, name";
+    protected static final String TENANT_INFO_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, tenantProfileName, title, email, country, state, city, address, address2, zip, phone, email";
     protected static final String DEVICE_PROFILE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, transportType, description, isDefault";
     protected static final String ASSET_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
     protected static final String ALARM_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, startTs, endTs, type, ackTs, clearTs, severity, status";

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

@@ -373,7 +373,7 @@ public class DeviceController extends BaseController {
 
     @ApiOperation(value = "Get Tenant Devices (getTenantDevices)",
             notes = "Returns a page of devices owned by tenant. " +
-                    PAGE_DATA_PARAMETERS)
+                    PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody

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

@@ -16,6 +16,8 @@
 package org.thingsboard.server.controller;
 
 import com.fasterxml.jackson.databind.node.ObjectNode;
+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.http.HttpStatus;
@@ -47,21 +49,26 @@ import org.thingsboard.server.service.security.permission.Resource;
 @Slf4j
 public class TenantController extends BaseController {
 
+    private static final String TENANT_INFO_DESCRIPTION = "The Tenant Info object extends regular Tenant object and includes Tenant Profile name. ";
     @Autowired
     private InstallScripts installScripts;
 
     @Autowired
     private TenantService tenantService;
 
+    @ApiOperation(value = "Get Tenant (getTenantById)",
+            notes = "Fetch the Tenant object based on the provided Tenant Id. " + SYSTEM_AND_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/{tenantId}", method = RequestMethod.GET)
     @ResponseBody
-    public Tenant getTenantById(@PathVariable("tenantId") String strTenantId) throws ThingsboardException {
+    public Tenant getTenantById(
+            @ApiParam(value = TENANT_ID_PARAM_DESCRIPTION)
+            @PathVariable(TENANT_ID) String strTenantId) throws ThingsboardException {
         checkParameter(TENANT_ID, strTenantId);
         try {
             TenantId tenantId = new TenantId(toUUID(strTenantId));
             Tenant tenant = checkTenantId(tenantId, Operation.READ);
-            if(!tenant.getAdditionalInfo().isNull()) {
+            if (!tenant.getAdditionalInfo().isNull()) {
                 processDashboardIdFromAdditionalInfo((ObjectNode) tenant.getAdditionalInfo(), HOME_DASHBOARD);
             }
             return tenant;
@@ -70,10 +77,15 @@ public class TenantController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Tenant Info (getTenantInfoById)",
+            notes = "Fetch the Tenant Info object based on the provided Tenant Id. " +
+                    TENANT_INFO_DESCRIPTION + SYSTEM_AND_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/info/{tenantId}", method = RequestMethod.GET)
     @ResponseBody
-    public TenantInfo getTenantInfoById(@PathVariable("tenantId") String strTenantId) throws ThingsboardException {
+    public TenantInfo getTenantInfoById(
+            @ApiParam(value = TENANT_ID_PARAM_DESCRIPTION)
+            @PathVariable(TENANT_ID) String strTenantId) throws ThingsboardException {
         checkParameter(TENANT_ID, strTenantId);
         try {
             TenantId tenantId = new TenantId(toUUID(strTenantId));
@@ -83,10 +95,18 @@ public class TenantController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Create Or update Tenant (saveTenant)",
+            notes = "Create or update the Tenant. When creating tenant, platform generates Tenant Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
+                    "Default Rule Chain and Device profile are also generated for the new tenants automatically. " +
+                    "The newly created Tenant Id will be present in the response. " +
+                    "Specify existing Tenant Id id to update the Tenant. " +
+                    "Referencing non-existing Tenant Id will cause 'Not Found' error." + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenant", method = RequestMethod.POST)
     @ResponseBody
-    public Tenant saveTenant(@RequestBody Tenant tenant) throws ThingsboardException {
+    public Tenant saveTenant(
+            @ApiParam(value = "A JSON value representing the tenant.")
+            @RequestBody Tenant tenant) throws ThingsboardException {
         try {
             boolean newTenant = tenant.getId() == null;
 
@@ -107,11 +127,15 @@ public class TenantController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Delete Tenant (deleteTenant)",
+            notes = "Deletes the tenant, it's customers, rule chains, devices and all other related entities. Referencing non-existing tenant Id will cause an error." + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenant/{tenantId}", method = RequestMethod.DELETE)
     @ResponseStatus(value = HttpStatus.OK)
-    public void deleteTenant(@PathVariable("tenantId") String strTenantId) throws ThingsboardException {
+    public void deleteTenant(
-        checkParameter("tenantId", strTenantId);
+            @ApiParam(value = TENANT_ID_PARAM_DESCRIPTION)
+            @PathVariable(TENANT_ID) String strTenantId) throws ThingsboardException {
+        checkParameter(TENANT_ID, strTenantId);
         try {
             TenantId tenantId = new TenantId(toUUID(strTenantId));
             Tenant tenant = checkTenantId(tenantId, Operation.DELETE);
@@ -124,14 +148,21 @@ public class TenantController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Tenants (getTenants)", notes = "Returns a page of tenants registered in the platform. " + PAGE_DATA_PARAMETERS + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenants", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
-    public PageData<Tenant> getTenants(@RequestParam int pageSize,
+    public PageData<Tenant> getTenants(
-                                       @RequestParam int page,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
-                                       @RequestParam(required = false) String textSearch,
+            @RequestParam int pageSize,
-                                       @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
-                                       @RequestParam(required = false) String sortOrder) throws ThingsboardException {
+            @RequestParam int page,
+            @ApiParam(value = TENANT_TEXT_SEARCH_DESCRIPTION)
+            @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = TENANT_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);
             return checkNotNull(tenantService.findTenants(pageLink));
@@ -140,14 +171,23 @@ public class TenantController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Tenants Info (getTenants)", notes = "Returns a page of tenant info objects registered in the platform. "
+            + TENANT_INFO_DESCRIPTION + PAGE_DATA_PARAMETERS + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
-    public PageData<TenantInfo> getTenantInfos(@RequestParam int pageSize,
+    public PageData<TenantInfo> getTenantInfos(
-                                               @RequestParam int page,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
-                                               @RequestParam(required = false) String textSearch,
+            @RequestParam int pageSize,
-                                               @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
-                                               @RequestParam(required = false) String sortOrder) throws ThingsboardException {
+            @RequestParam int page,
+            @ApiParam(value = TENANT_TEXT_SEARCH_DESCRIPTION)
+            @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = TENANT_INFO_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);
             return checkNotNull(tenantService.findTenantInfos(pageLink));

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

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.controller;
 
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatus;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -44,10 +46,16 @@ import org.thingsboard.server.service.security.permission.Resource;
 @Slf4j
 public class TenantProfileController extends BaseController {
 
+    private static final String TENANT_PROFILE_INFO_DESCRIPTION = "Tenant Profile Info is a lightweight object that contains only id and name of the profile. ";
+
+    @ApiOperation(value = "Get Tenant Profile (getTenantProfileById)",
+            notes = "Fetch the Tenant Profile object based on the provided Tenant Profile Id. " + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfile/{tenantProfileId}", method = RequestMethod.GET)
     @ResponseBody
-    public TenantProfile getTenantProfileById(@PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
+    public TenantProfile getTenantProfileById(
+            @ApiParam(value = TENANT_PROFILE_ID_PARAM_DESCRIPTION)
+            @PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
         checkParameter("tenantProfileId", strTenantProfileId);
         try {
             TenantProfileId tenantProfileId = new TenantProfileId(toUUID(strTenantProfileId));
@@ -57,10 +65,14 @@ public class TenantProfileController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Tenant Profile Info (getTenantProfileInfoById)",
+            notes = "Fetch the Tenant Profile Info object based on the provided Tenant Profile Id. " + TENANT_PROFILE_INFO_DESCRIPTION + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfileInfo/{tenantProfileId}", method = RequestMethod.GET)
     @ResponseBody
-    public EntityInfo getTenantProfileInfoById(@PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
+    public EntityInfo getTenantProfileInfoById(
+            @ApiParam(value = TENANT_PROFILE_ID_PARAM_DESCRIPTION)
+            @PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
         checkParameter("tenantProfileId", strTenantProfileId);
         try {
             TenantProfileId tenantProfileId = new TenantProfileId(toUUID(strTenantProfileId));
@@ -70,6 +82,8 @@ public class TenantProfileController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get default Tenant Profile Info (getDefaultTenantProfileInfo)",
+            notes = "Fetch the default Tenant Profile Info object based. " + TENANT_PROFILE_INFO_DESCRIPTION + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfileInfo/default", method = RequestMethod.GET)
     @ResponseBody
@@ -81,10 +95,19 @@ public class TenantProfileController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Create Or update Tenant Profile (saveTenantProfile)",
+            notes = "Create or update the Tenant Profile. When creating tenant profile, platform generates Tenant Profile Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
+                    "The newly created Tenant Profile Id will be present in the response. " +
+                    "Specify existing Tenant Profile Id id to update the Tenant Profile. " +
+                    "Referencing non-existing Tenant Profile Id will cause 'Not Found' error. " +
+                    "Update of the tenant profile configuration will cause immediate recalculation of API limits for all affected Tenants. " +
+                    SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfile", method = RequestMethod.POST)
     @ResponseBody
-    public TenantProfile saveTenantProfile(@RequestBody TenantProfile tenantProfile) throws ThingsboardException {
+    public TenantProfile saveTenantProfile(
+            @ApiParam(value = "A JSON value representing the tenant profile.")
+            @RequestBody TenantProfile tenantProfile) throws ThingsboardException {
         try {
             boolean newTenantProfile = tenantProfile.getId() == null;
             if (newTenantProfile) {
@@ -105,10 +128,14 @@ public class TenantProfileController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Delete Tenant Profile (deleteTenantProfile)",
+            notes = "Deletes the tenant profile. Referencing non-existing tenant profile Id will cause an error. Referencing profile that is used by the tenants will cause an error. " + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfile/{tenantProfileId}", method = RequestMethod.DELETE)
     @ResponseStatus(value = HttpStatus.OK)
-    public void deleteTenantProfile(@PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
+    public void deleteTenantProfile(
+            @ApiParam(value = TENANT_PROFILE_ID_PARAM_DESCRIPTION)
+            @PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
         checkParameter("tenantProfileId", strTenantProfileId);
         try {
             TenantProfileId tenantProfileId = new TenantProfileId(toUUID(strTenantProfileId));
@@ -120,10 +147,14 @@ public class TenantProfileController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Make tenant profile default (setDefaultTenantProfile)",
+            notes = "Makes specified tenant profile to be default. Referencing non-existing tenant profile Id will cause an error. " + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfile/{tenantProfileId}/default", method = RequestMethod.POST)
     @ResponseBody
-    public TenantProfile setDefaultTenantProfile(@PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
+    public TenantProfile setDefaultTenantProfile(
+            @ApiParam(value = TENANT_PROFILE_ID_PARAM_DESCRIPTION)
+            @PathVariable("tenantProfileId") String strTenantProfileId) throws ThingsboardException {
         checkParameter("tenantProfileId", strTenantProfileId);
         try {
             TenantProfileId tenantProfileId = new TenantProfileId(toUUID(strTenantProfileId));
@@ -135,14 +166,21 @@ public class TenantProfileController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Tenant Profiles (getTenantProfiles)", notes = "Returns a page of tenant profiles registered in the platform. " + PAGE_DATA_PARAMETERS + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfiles", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
-    public PageData<TenantProfile> getTenantProfiles(@RequestParam int pageSize,
+    public PageData<TenantProfile> getTenantProfiles(
-                                                     @RequestParam int page,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
-                                                     @RequestParam(required = false) String textSearch,
+            @RequestParam int pageSize,
-                                                     @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
-                                                     @RequestParam(required = false) String sortOrder) throws ThingsboardException {
+            @RequestParam int page,
+            @ApiParam(value = TENANT_PROFILE_TEXT_SEARCH_DESCRIPTION)
+            @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = TENANT_PROFILE_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);
             return checkNotNull(tenantProfileService.findTenantProfiles(getTenantId(), pageLink));
@@ -151,14 +189,22 @@ public class TenantProfileController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Tenant Profiles Info (getTenantProfileInfos)", notes = "Returns a page of tenant profile info objects registered in the platform. "
+            + TENANT_PROFILE_INFO_DESCRIPTION + PAGE_DATA_PARAMETERS + SYSTEM_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('SYS_ADMIN')")
     @RequestMapping(value = "/tenantProfileInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
-    public PageData<EntityInfo> getTenantProfileInfos(@RequestParam int pageSize,
+    public PageData<EntityInfo> getTenantProfileInfos(
-                                                      @RequestParam int page,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
-                                                      @RequestParam(required = false) String textSearch,
+            @RequestParam int pageSize,
-                                                      @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
-                                                      @RequestParam(required = false) String sortOrder) throws ThingsboardException {
+            @RequestParam int page,
+            @ApiParam(value = TENANT_PROFILE_TEXT_SEARCH_DESCRIPTION)
+            @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = TENANT_PROFILE_INFO_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);
             return checkNotNull(tenantProfileService.findTenantProfileInfos(getTenantId(), pageLink));

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

@@ -18,6 +18,8 @@ package org.thingsboard.server.common.data;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonProperty.Access;
+import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.annotations.ApiModelProperty;
 import org.thingsboard.server.common.data.id.CustomerId;
 import org.thingsboard.server.common.data.id.TenantId;
 import org.thingsboard.server.common.data.validation.NoXss;
@@ -27,7 +29,9 @@ public class Customer extends ContactBased<CustomerId> implements HasTenantId {
     private static final long serialVersionUID = -1599722990298929275L;
 
     @NoXss
+    @ApiModelProperty(position = 3, value = "Title of the customer", example = "Company A")
     private String title;
+    @ApiModelProperty(position = 5, required = true, value = "JSON object with Tenant Id")
     private TenantId tenantId;
 
     public Customer() {
@@ -60,6 +64,75 @@ public class Customer extends ContactBased<CustomerId> implements HasTenantId {
         this.title = title;
     }
 
+    @ApiModelProperty(position = 1, value = "JSON object with the customer Id. " +
+            "Specify this field to update the customer. " +
+            "Referencing non-existing customer Id will cause error. " +
+            "Omit this field to create new customer." )
+    @Override
+    public CustomerId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "Timestamp of the customer creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
+
+    @ApiModelProperty(position = 6, required = true, value = "Country", example = "US")
+    @Override
+    public String getCountry() {
+        return super.getCountry();
+    }
+
+    @ApiModelProperty(position = 7, required = true, value = "State", example = "NY")
+    @Override
+    public String getState() {
+        return super.getState();
+    }
+
+    @ApiModelProperty(position = 8, required = true, value = "City", example = "New York")
+    @Override
+    public String getCity() {
+        return super.getCity();
+    }
+
+    @ApiModelProperty(position = 9, required = true, value = "Address Line 1", example = "42 Broadway Suite 12-400")
+    @Override
+    public String getAddress() {
+        return super.getAddress();
+    }
+
+    @ApiModelProperty(position = 10, required = true, value = "Address Line 2", example = "")
+    @Override
+    public String getAddress2() {
+        return super.getAddress2();
+    }
+
+    @ApiModelProperty(position = 11, required = true, value = "Zip code", example = "10004")
+    @Override
+    public String getZip() {
+        return super.getZip();
+    }
+
+    @ApiModelProperty(position = 12, required = true, value = "Phone number", example = "+1(415)777-7777")
+    @Override
+    public String getPhone() {
+        return super.getPhone();
+    }
+
+    @ApiModelProperty(position = 13, required = true, value = "Email", example = "example@company.com")
+    @Override
+    public String getEmail() {
+        return super.getEmail();
+    }
+
+    @ApiModelProperty(position = 14, value = "Additional parameters of the device", dataType = "com.fasterxml.jackson.databind.JsonNode")
+    @Override
+    public JsonNode getAdditionalInfo() {
+        return super.getAdditionalInfo();
+    }
+
     @JsonIgnore
     public boolean isPublic() {
         if (getAdditionalInfo() != null && getAdditionalInfo().has("isPublic")) {
@@ -76,6 +149,7 @@ public class Customer extends ContactBased<CustomerId> implements HasTenantId {
 
     @Override
     @JsonProperty(access = Access.READ_ONLY)
+    @ApiModelProperty(position = 4, value = "Name of the customer. Read-only, duplicated from title for backward compatibility", example = "Company A", readOnly = true)
     public String getName() {
         return title;
     }

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

@@ -17,6 +17,7 @@ package org.thingsboard.server.common.data;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
 import lombok.Value;
@@ -31,9 +32,13 @@ import java.util.UUID;
 @ToString(callSuper = true)
 public class DeviceProfileInfo extends EntityInfo {
 
+    @ApiModelProperty(position = 3, value = "Either URL or Base64 data of the icon. Used in the mobile application to visualize set of device profiles in the grid view. ")
     private final String image;
+    @ApiModelProperty(position = 4, value = "Reference to the dashboard. Used in the mobile application to open the default dashboard when user navigates to device details.")
     private final DashboardId defaultDashboardId;
+    @ApiModelProperty(position = 5, value = "Type of the profile. Always 'DEFAULT' for now. Reserved for future use.")
     private final DeviceProfileType type;
+    @ApiModelProperty(position = 6, value = "Type of the transport used to connect the device. Default transport supports HTTP, CoAP and MQTT.")
     private final DeviceTransportType transportType;
 
     @JsonCreator

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

@@ -17,6 +17,8 @@ package org.thingsboard.server.common.data;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.id.EntityId;
 import org.thingsboard.server.common.data.id.EntityIdFactory;
@@ -24,10 +26,13 @@ import org.thingsboard.server.common.data.id.HasId;
 
 import java.util.UUID;
 
+@ApiModel
 @Data
 public class EntityInfo implements HasId<EntityId>, HasName {
 
+    @ApiModelProperty(position = 1, value = "JSON object with the entity Id. ")
     private final EntityId id;
+    @ApiModelProperty(position = 2, value = "Entity Name")
     private final String name;
 
     @JsonCreator

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

@@ -17,20 +17,28 @@ package org.thingsboard.server.common.data;
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.EqualsAndHashCode;
 import org.thingsboard.server.common.data.id.TenantId;
 import org.thingsboard.server.common.data.id.TenantProfileId;
 import org.thingsboard.server.common.data.validation.NoXss;
 
+@ApiModel
 @EqualsAndHashCode(callSuper = true)
 public class Tenant extends ContactBased<TenantId> implements HasTenantId {
 
     private static final long serialVersionUID = 8057243243859922101L;
 
     @NoXss
+    @ApiModelProperty(position = 3, value = "Title of the tenant", example = "Company A")
     private String title;
     @NoXss
+    @ApiModelProperty(position = 5, value = "Geo region of the tenant", example = "North America")
     private String region;
+
+    @ApiModelProperty(position = 6, required = true, value = "JSON object with Tenant Profile Id")
     private TenantProfileId tenantProfileId;
 
     public Tenant() {
@@ -63,6 +71,7 @@ public class Tenant extends ContactBased<TenantId> implements HasTenantId {
     }
 
     @Override
+    @ApiModelProperty(position = 4, value = "Name of the tenant. Read-only, duplicated from title for backward compatibility", example = "Company A", readOnly = true)
     @JsonProperty(access = JsonProperty.Access.READ_ONLY)
     public String getName() {
         return title;
@@ -89,6 +98,75 @@ public class Tenant extends ContactBased<TenantId> implements HasTenantId {
         return getTitle();
     }
 
+    @ApiModelProperty(position = 1, value = "JSON object with the tenant Id. " +
+            "Specify this field to update the tenant. " +
+            "Referencing non-existing tenant Id will cause error. " +
+            "Omit this field to create new tenant." )
+    @Override
+    public TenantId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "Timestamp of the tenant creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
+
+    @ApiModelProperty(position = 7, required = true, value = "Country", example = "US")
+    @Override
+    public String getCountry() {
+        return super.getCountry();
+    }
+
+    @ApiModelProperty(position = 8, required = true, value = "State", example = "NY")
+    @Override
+    public String getState() {
+        return super.getState();
+    }
+
+    @ApiModelProperty(position = 9, required = true, value = "City", example = "New York")
+    @Override
+    public String getCity() {
+        return super.getCity();
+    }
+
+    @ApiModelProperty(position = 10, required = true, value = "Address Line 1", example = "42 Broadway Suite 12-400")
+    @Override
+    public String getAddress() {
+        return super.getAddress();
+    }
+
+    @ApiModelProperty(position = 11, required = true, value = "Address Line 2", example = "")
+    @Override
+    public String getAddress2() {
+        return super.getAddress2();
+    }
+
+    @ApiModelProperty(position = 12, required = true, value = "Zip code", example = "10004")
+    @Override
+    public String getZip() {
+        return super.getZip();
+    }
+
+    @ApiModelProperty(position = 13, required = true, value = "Phone number", example = "+1(415)777-7777")
+    @Override
+    public String getPhone() {
+        return super.getPhone();
+    }
+
+    @ApiModelProperty(position = 14, required = true, value = "Email", example = "example@company.com")
+    @Override
+    public String getEmail() {
+        return super.getEmail();
+    }
+
+    @ApiModelProperty(position = 15, value = "Additional parameters of the device", dataType = "com.fasterxml.jackson.databind.JsonNode")
+    @Override
+    public JsonNode getAdditionalInfo() {
+        return super.getAdditionalInfo();
+    }
+
     @Override
     public String toString() {
         StringBuilder builder = new StringBuilder();

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

@@ -15,12 +15,15 @@
  */
 package org.thingsboard.server.common.data;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.id.TenantId;
 
+@ApiModel
 @Data
 public class TenantInfo extends Tenant {
-
+    @ApiModelProperty(position = 15, value = "Tenant Profile name", example = "Default")
     private String tenantProfileName;
 
     public TenantInfo() {

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

@@ -17,6 +17,8 @@ package org.thingsboard.server.common.data;
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.core.JsonProcessingException;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import lombok.extern.slf4j.Slf4j;
@@ -31,18 +33,27 @@ import java.util.Optional;
 
 import static org.thingsboard.server.common.data.SearchTextBasedWithAdditionalInfo.mapper;
 
+@ApiModel
 @Data
 @EqualsAndHashCode(callSuper = true)
 @Slf4j
 public class TenantProfile extends SearchTextBased<TenantProfileId> implements HasName {
 
     @NoXss
+    @ApiModelProperty(position = 3, value = "Name of the tenant profile", example = "High Priority Tenants")
     private String name;
     @NoXss
+    @ApiModelProperty(position = 4, value = "Description of the tenant profile", example = "Any text")
     private String description;
+    @ApiModelProperty(position = 5, value = "Default Tenant profile to be used.", example = "true")
     private boolean isDefault;
+    @ApiModelProperty(position = 6, value = "If enabled, will push all messages related to this tenant and processed by core platform services into separate queue. " +
+            "Useful for complex microservices deployments, to isolate processing of the data for specific tenants", example = "true")
     private boolean isolatedTbCore;
+    @ApiModelProperty(position = 7, value = "If enabled, will push all messages related to this tenant and processed by the rule engine into separate queue. " +
+            "Useful for complex microservices deployments, to isolate processing of the data for specific tenants", example = "true")
     private boolean isolatedTbRuleEngine;
+    @ApiModelProperty(position = 8, value = "Complex JSON object that contains profile settings: max devices, max assets, rate limits, etc.")
     private transient TenantProfileData profileData;
     @JsonIgnore
     private byte[] profileDataBytes;
@@ -65,6 +76,21 @@ public class TenantProfile extends SearchTextBased<TenantProfileId> implements H
         this.setProfileData(tenantProfile.getProfileData());
     }
 
+    @ApiModelProperty(position = 1, value = "JSON object with the tenant profile Id. " +
+            "Specify this field to update the tenant profile. " +
+            "Referencing non-existing tenant profile Id will cause error. " +
+            "Omit this field to create new tenant profile." )
+    @Override
+    public TenantProfileId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "Timestamp of the tenant profile creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
+
     @Override
     public String getSearchText() {
         return getName();

common/data/src/main/java/org/thingsboard/server/common/data/tenant/profile/DefaultTenantProfileConfiguration.java

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.common.data.tenant.profile;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Data;

common/data/src/main/java/org/thingsboard/server/common/data/tenant/profile/TenantProfileConfiguration.java

@@ -19,6 +19,7 @@ import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import io.swagger.annotations.ApiModel;
 import org.thingsboard.server.common.data.ApiUsageRecordKey;
 import org.thingsboard.server.common.data.TenantProfileType;
 

common/data/src/main/java/org/thingsboard/server/common/data/tenant/profile/TenantProfileData.java

@@ -15,11 +15,15 @@
  */
 package org.thingsboard.server.common.data.tenant.profile;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
+@ApiModel
 @Data
 public class TenantProfileData {
 
+    @ApiModelProperty(position = 1, value = "Complex JSON object that contains profile settings: max devices, max assets, rate limits, etc.")
     private TenantProfileConfiguration configuration;
 
 }