Widget Type description

@@ -180,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'";
     public static final String WIDGET_BUNDLE_ID_PARAM_DESCRIPTION = "A string value representing the widget bundle id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
+    public static final String WIDGET_TYPE_ID_PARAM_DESCRIPTION = "A string value representing the widget type 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_OR_TENANT_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority.";
@@ -198,7 +200,6 @@ public abstract class BaseController {
     protected static final String ASSET_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the asset name.";
     protected static final String DASHBOARD_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the dashboard title.";
     protected static final String WIDGET_BUNDLE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the widget bundle title.";
-    protected static final String WIDGET_TYPE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the widget type 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 USER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the user email.";
@@ -227,7 +228,6 @@ public abstract class BaseController {
     protected static final String EDGE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
     protected static final String RULE_CHAIN_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, root";
     protected static final String WIDGET_BUNDLE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, tenantId";
-    protected static final String WIDGET_TYPE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, alias, bundleAlias, name";
     protected static final String AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, entityType, entityName, userName, actionType, actionStatus";
     protected static final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESC (DESCENDING)";
     protected static final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";

@@ -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;
@@ -48,10 +50,20 @@ import java.util.List;
 @RequestMapping("/api")
 public class WidgetTypeController extends BaseController {
 
+    private static final String WIDGET_TYPE_DESCRIPTION = "Widget Type represents the template for widget creation. Widget Type and Widget are similar to class and object in OOP theory.";
+    private static final String WIDGET_TYPE_DETAILS_DESCRIPTION = "Widget Type Details extend Widget Type and add image and description properties. " +
+            "Those properties are useful to edit the Widget Type but they are not required for Dashboard rendering. ";
+    private static final String WIDGET_TYPE_INFO_DESCRIPTION = "Widget Type Info is a lightweight object that represents Widget Type but does not contain the heavyweight widget descriptor JSON";
+
+
+    @ApiOperation(value = "Get Widget Type Details (getWidgetTypeById)",
+            notes = "Get the Widget Type Details based on the provided Widget Type Id. " + WIDGET_TYPE_DETAILS_DESCRIPTION + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/widgetType/{widgetTypeId}", method = RequestMethod.GET)
     @ResponseBody
-    public WidgetTypeDetails getWidgetTypeById(@PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
+    public WidgetTypeDetails getWidgetTypeById(
+            @ApiParam(value = WIDGET_TYPE_ID_PARAM_DESCRIPTION, required = true)
+            @PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
         checkParameter("widgetTypeId", strWidgetTypeId);
         try {
             WidgetTypeId widgetTypeId = new WidgetTypeId(toUUID(strWidgetTypeId));
@@ -61,10 +73,21 @@ public class WidgetTypeController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Create Or Update Widget Type (saveWidgetType)",
+            notes = "Create or update the Widget Type. " + WIDGET_TYPE_DESCRIPTION + " " +
+                    "When creating the Widget Type, platform generates Widget Type Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
+                    "The newly created Widget Type Id will be present in the response. " +
+                    "Specify existing Widget Type id to update the Widget Type. " +
+                    "Referencing non-existing Widget Type Id will cause 'Not Found' error." +
+                    "\n\nWidget Type alias is unique in the scope of Widget Bundle. " +
+                    "Special Tenant Id '13814000-1dd2-11b2-8080-808080808080' is automatically used if the create request is sent by user with 'SYS_ADMIN' authority."
+                    + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/widgetType", method = RequestMethod.POST)
     @ResponseBody
-    public WidgetTypeDetails saveWidgetType(@RequestBody WidgetTypeDetails widgetTypeDetails) throws ThingsboardException {
+    public WidgetTypeDetails saveWidgetType(
+            @ApiParam(value = "A JSON value representing the Widget Type Details.", required = true)
+            @RequestBody WidgetTypeDetails widgetTypeDetails) throws ThingsboardException {
         try {
             if (Authority.SYS_ADMIN.equals(getCurrentUser().getAuthority())) {
                 widgetTypeDetails.setTenantId(TenantId.SYS_TENANT_ID);
@@ -84,10 +107,14 @@ public class WidgetTypeController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Delete widget type (deleteWidgetType)",
+            notes = "Deletes the  Widget Type. Referencing non-existing Widget Type Id will cause an error." + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/widgetType/{widgetTypeId}", method = RequestMethod.DELETE)
     @ResponseStatus(value = HttpStatus.OK)
-    public void deleteWidgetType(@PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
+    public void deleteWidgetType(
+            @ApiParam(value = WIDGET_TYPE_ID_PARAM_DESCRIPTION, required = true)
+            @PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
         checkParameter("widgetTypeId", strWidgetTypeId);
         try {
             WidgetTypeId widgetTypeId = new WidgetTypeId(toUUID(strWidgetTypeId));
@@ -101,11 +128,15 @@ public class WidgetTypeController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get all Widget types for specified Bundle (getBundleWidgetTypes)",
+            notes = "Returns an array of Widget Type objects that belong to specified Widget Bundle." + WIDGET_TYPE_DESCRIPTION + " " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/widgetTypes", params = {"isSystem", "bundleAlias"}, method = RequestMethod.GET)
     @ResponseBody
     public List<WidgetType> getBundleWidgetTypes(
+            @ApiParam(value = "System or Tenant", required = true)
             @RequestParam boolean isSystem,
+            @ApiParam(value = "Widget Bundle alias", required = true)
             @RequestParam String bundleAlias) throws ThingsboardException {
         try {
             TenantId tenantId;
@@ -120,11 +151,15 @@ public class WidgetTypeController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get all Widget types details for specified Bundle (getBundleWidgetTypes)",
+            notes = "Returns an array of Widget Type Details objects that belong to specified Widget Bundle." + WIDGET_TYPE_DETAILS_DESCRIPTION + " " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/widgetTypesDetails", params = {"isSystem", "bundleAlias"}, method = RequestMethod.GET)
     @ResponseBody
     public List<WidgetTypeDetails> getBundleWidgetTypesDetails(
+            @ApiParam(value = "System or Tenant", required = true)
             @RequestParam boolean isSystem,
+            @ApiParam(value = "Widget Bundle alias", required = true)
             @RequestParam String bundleAlias) throws ThingsboardException {
         try {
             TenantId tenantId;
@@ -139,11 +174,15 @@ public class WidgetTypeController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Widget Type Info objects (getBundleWidgetTypesInfos)",
+            notes = "Get the Widget Type Info objects based on the provided parameters. " + WIDGET_TYPE_INFO_DESCRIPTION + AVAILABLE_FOR_ANY_AUTHORIZED_USER)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/widgetTypesInfos", params = {"isSystem", "bundleAlias"}, method = RequestMethod.GET)
     @ResponseBody
     public List<WidgetTypeInfo> getBundleWidgetTypesInfos(
+            @ApiParam(value = "System or Tenant", required = true)
             @RequestParam boolean isSystem,
+            @ApiParam(value = "Widget Bundle alias", required = true)
             @RequestParam String bundleAlias) throws ThingsboardException {
         try {
             TenantId tenantId;
@@ -158,12 +197,17 @@ public class WidgetTypeController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Widget Type (getWidgetType)",
+            notes = "Get the Widget Type based on the provided parameters. " + WIDGET_TYPE_DESCRIPTION + AVAILABLE_FOR_ANY_AUTHORIZED_USER)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/widgetType", params = {"isSystem", "bundleAlias", "alias"}, method = RequestMethod.GET)
     @ResponseBody
     public WidgetType getWidgetType(
+            @ApiParam(value = "System or Tenant", required = true)
             @RequestParam boolean isSystem,
+            @ApiParam(value = "Widget Bundle alias", required = true)
             @RequestParam String bundleAlias,
+            @ApiParam(value = "Widget Type alias", required = true)
             @RequestParam String alias) throws ThingsboardException {
         try {
             TenantId tenantId;

@@ -54,7 +54,7 @@ public class WidgetsBundleController extends BaseController {
     @RequestMapping(value = "/widgetsBundle/{widgetsBundleId}", method = RequestMethod.GET)
     @ResponseBody
     public WidgetsBundle getWidgetsBundleById(
-            @ApiParam(value = WIDGET_BUNDLE_ID_PARAM_DESCRIPTION)
+            @ApiParam(value = WIDGET_BUNDLE_ID_PARAM_DESCRIPTION, required = true)
             @PathVariable("widgetsBundleId") String strWidgetsBundleId) throws ThingsboardException {
         checkParameter("widgetsBundleId", strWidgetsBundleId);
         try {
@@ -78,7 +78,7 @@ public class WidgetsBundleController extends BaseController {
     @RequestMapping(value = "/widgetsBundle", method = RequestMethod.POST)
     @ResponseBody
     public WidgetsBundle saveWidgetsBundle(
-            @ApiParam(value = "A JSON value representing the Widget Bundle.")
+            @ApiParam(value = "A JSON value representing the Widget Bundle.", required = true)
             @RequestBody WidgetsBundle widgetsBundle) throws ThingsboardException {
         try {
             if (Authority.SYS_ADMIN.equals(getCurrentUser().getAuthority())) {
@@ -104,7 +104,9 @@ public class WidgetsBundleController extends BaseController {
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
     @RequestMapping(value = "/widgetsBundle/{widgetsBundleId}", method = RequestMethod.DELETE)
     @ResponseStatus(value = HttpStatus.OK)
-    public void deleteWidgetsBundle(@PathVariable("widgetsBundleId") String strWidgetsBundleId) throws ThingsboardException {
+    public void deleteWidgetsBundle(
+            @ApiParam(value = WIDGET_BUNDLE_ID_PARAM_DESCRIPTION, required = true)
+            @PathVariable("widgetsBundleId") String strWidgetsBundleId) throws ThingsboardException {
         checkParameter("widgetsBundleId", strWidgetsBundleId);
         try {
             WidgetsBundleId widgetsBundleId = new WidgetsBundleId(toUUID(strWidgetsBundleId));

@@ -15,6 +15,7 @@
  */
 package org.thingsboard.server.common.data.widget;
 
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.BaseData;
 import org.thingsboard.server.common.data.HasTenantId;
@@ -27,12 +28,16 @@ public class BaseWidgetType extends BaseData<WidgetTypeId> implements HasTenantI
 
     private static final long serialVersionUID = 8388684344603660756L;
 
+    @ApiModelProperty(position = 3, value = "JSON object with Tenant Id.", readOnly = true)
     private TenantId tenantId;
     @NoXss
+    @ApiModelProperty(position = 4, value = "Reference to widget bundle", readOnly = true)
     private String bundleAlias;
     @NoXss
+    @ApiModelProperty(position = 5, value = "Unique alias that is used in dashboards as a reference widget type", readOnly = true)
     private String alias;
     @NoXss
+    @ApiModelProperty(position = 6, value = "Widget name used in search and UI", readOnly = true)
     private String name;
 
     public BaseWidgetType() {
@@ -50,4 +55,19 @@ public class BaseWidgetType extends BaseData<WidgetTypeId> implements HasTenantI
         this.alias = widgetType.getAlias();
         this.name = widgetType.getName();
     }
+
+    @ApiModelProperty(position = 1, value = "JSON object with the Widget Type Id. " +
+            "Specify this field to update the Widget Type. " +
+            "Referencing non-existing Widget Type Id will cause error. " +
+            "Omit this field to create new Widget Type." )
+    @Override
+    public WidgetTypeId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "Timestamp of the Widget Type creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
 }

@@ -16,12 +16,14 @@
 package org.thingsboard.server.common.data.widget;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.id.WidgetTypeId;
 
 @Data
 public class WidgetType extends BaseWidgetType {
 
+    @ApiModelProperty(position = 7, value = "Complex JSON object that describes the widget type", readOnly = true)
     private transient JsonNode descriptor;
 
     public WidgetType() {

@@ -16,6 +16,7 @@
 package org.thingsboard.server.common.data.widget;
 
 import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.id.WidgetTypeId;
 import org.thingsboard.server.common.data.validation.NoXss;
@@ -24,8 +25,10 @@ import org.thingsboard.server.common.data.validation.NoXss;
 @JsonPropertyOrder({ "alias", "name", "image", "description", "descriptor" })
 public class WidgetTypeDetails extends WidgetType {
 
+    @ApiModelProperty(position = 8, value = "Base64 encoded thumbnail", readOnly = true)
     private String image;
     @NoXss
+    @ApiModelProperty(position = 9, value = "Description of the widget", readOnly = true)
     private String description;
 
     public WidgetTypeDetails() {

@@ -15,6 +15,7 @@
  */
 package org.thingsboard.server.common.data.widget;
 
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.id.WidgetTypeId;
 import org.thingsboard.server.common.data.validation.NoXss;
@@ -22,10 +23,13 @@ import org.thingsboard.server.common.data.validation.NoXss;
 @Data
 public class WidgetTypeInfo extends BaseWidgetType {
 
+    @ApiModelProperty(position = 7, value = "Base64 encoded widget thumbnail", readOnly = true)
     private String image;
     @NoXss
+    @ApiModelProperty(position = 7, value = "Description of the widget type", readOnly = true)
     private String description;
     @NoXss
+    @ApiModelProperty(position = 8, value = "Type of the widget (timeseries, latest, control, alarm or static)", readOnly = true)
     private String widgetType;
 
     public WidgetTypeInfo() {