Component Descriptor documentation

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.controller;
 
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import org.apache.commons.lang3.StringUtils;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -38,10 +40,20 @@ import java.util.Set;
 @RequestMapping("/api")
 public class ComponentDescriptorController extends BaseController {
 
+    private static final String COMPONENT_DESCRIPTOR_DEFINITION = "Each Component Descriptor represents configuration of specific rule node (e.g. 'Save Timeseries' or 'Send Email'.). " +
+            "The Component Descriptors are used by the rule chain Web UI to build the configuration forms for the rule nodes. " +
+            "The Component Descriptors are discovered at runtime by scanning the class path and searching for @RuleNode annotation. " +
+            "Once discovered, the up to date list of descriptors is persisted to the database.";
+
+    @ApiOperation(value = "Get Component Descriptor (getComponentDescriptorByClazz)",
+            notes = "Gets the Component Descriptor object using class name from the path parameters. " +
+                    COMPONENT_DESCRIPTOR_DEFINITION)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN')")
     @RequestMapping(value = "/component/{componentDescriptorClazz:.+}", method = RequestMethod.GET)
     @ResponseBody
-    public ComponentDescriptor getComponentDescriptorByClazz(@PathVariable("componentDescriptorClazz") String strComponentDescriptorClazz) throws ThingsboardException {
+    public ComponentDescriptor getComponentDescriptorByClazz(
+            @ApiParam(value = "Component Descriptor class name", required = true)
+            @PathVariable("componentDescriptorClazz") String strComponentDescriptorClazz) throws ThingsboardException {
         checkParameter("strComponentDescriptorClazz", strComponentDescriptorClazz);
         try {
             return checkComponentDescriptorByClazz(strComponentDescriptorClazz);
@@ -50,11 +62,17 @@ public class ComponentDescriptorController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Component Descriptors (getComponentDescriptorsByType)",
+            notes = "Gets the Component Descriptors using rule node type and optional rule chain type request parameters. " +
+                    COMPONENT_DESCRIPTOR_DEFINITION)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN')")
     @RequestMapping(value = "/components/{componentType}", method = RequestMethod.GET)
     @ResponseBody
-    public List<ComponentDescriptor> getComponentDescriptorsByType(@PathVariable("componentType") String strComponentType,
-                                                                   @RequestParam(value = "ruleChainType", required = false) String strRuleChainType) throws ThingsboardException {
+    public List<ComponentDescriptor> getComponentDescriptorsByType(
+            @ApiParam(value = "Type of the Rule Node", allowableValues = "ENRICHMENT,FILTER,TRANSFORMATION,ACTION,EXTERNAL", required = true)
+            @PathVariable("componentType") String strComponentType,
+            @ApiParam(value = "Type of the Rule Chain", allowableValues = "CORE,EDGE")
+            @RequestParam(value = "ruleChainType", required = false) String strRuleChainType) throws ThingsboardException {
         checkParameter("componentType", strComponentType);
         try {
             return checkComponentDescriptorsByType(ComponentType.valueOf(strComponentType), getRuleChainType(strRuleChainType));
@@ -63,11 +81,17 @@ public class ComponentDescriptorController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Component Descriptors (getComponentDescriptorsByTypes)",
+            notes = "Gets the Component Descriptors using coma separated list of rule node types and optional rule chain type request parameters. " +
+                    COMPONENT_DESCRIPTOR_DEFINITION)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN')")
     @RequestMapping(value = "/components", params = {"componentTypes"}, method = RequestMethod.GET)
     @ResponseBody
-    public List<ComponentDescriptor> getComponentDescriptorsByTypes(@RequestParam("componentTypes") String[] strComponentTypes,
-                                                                    @RequestParam(value = "ruleChainType", required = false) String strRuleChainType) throws ThingsboardException {
+    public List<ComponentDescriptor> getComponentDescriptorsByTypes(
+            @ApiParam(value = "List of types of the Rule Nodes, (ENRICHMENT, FILTER, TRANSFORMATION, ACTION or EXTERNAL)", required = true)
+            @RequestParam("componentTypes") String[] strComponentTypes,
+            @ApiParam(value = "Type of the Rule Chain", allowableValues = "CORE,EDGE")
+            @RequestParam(value = "ruleChainType", required = false) String strRuleChainType) throws ThingsboardException {
         checkArrayParameter("componentTypes", strComponentTypes);
         try {
             Set<ComponentType> componentTypes = new HashSet<>();

@@ -16,6 +16,8 @@
 package org.thingsboard.server.common.data.plugin;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.*;
 import org.thingsboard.server.common.data.SearchTextBased;
 import org.thingsboard.server.common.data.id.ComponentDescriptorId;
@@ -23,16 +25,23 @@ import org.thingsboard.server.common.data.id.ComponentDescriptorId;
 /**
  * @author Andrew Shvayka
  */
+@ApiModel
 @ToString
 public class ComponentDescriptor extends SearchTextBased<ComponentDescriptorId> {
 
     private static final long serialVersionUID = 1L;
 
+    @ApiModelProperty(position = 3, value = "Type of the Rule Node", readOnly = true)
     @Getter @Setter private ComponentType type;
+    @ApiModelProperty(position = 4, value = "Scope of the Rule Node. Always set to 'TENANT', since no rule chains on the 'SYSTEM' level yet.", readOnly = true, allowableValues = "TENANT", example = "TENANT")
     @Getter @Setter private ComponentScope scope;
+    @ApiModelProperty(position = 5, value = "Name of the Rule Node. Taken from the @RuleNode annotation.", readOnly = true, example = "Custom Rule Node")
     @Getter @Setter private String name;
+    @ApiModelProperty(position = 6, value = "Full name of the Java class that implements the Rule Engine Node interface.", readOnly = true, example = "com.mycompany.CustomRuleNode")
     @Getter @Setter private String clazz;
+    @ApiModelProperty(position = 7, value = "Complex JSON object that represents the Rule Node configuration.", readOnly = true)
     @Getter @Setter private transient JsonNode configurationDescriptor;
+    @ApiModelProperty(position = 8, value = "Rule Node Actions. Deprecated. Always null.", readOnly = true)
     @Getter @Setter private String actions;
 
     public ComponentDescriptor() {
@@ -53,12 +62,26 @@ public class ComponentDescriptor extends SearchTextBased<ComponentDescriptorId>
         this.actions = plugin.getActions();
     }
 
+    @ApiModelProperty(position = 1, value = "JSON object with the descriptor Id. " +
+            "Specify existing descriptor id to update the descriptor. " +
+            "Referencing non-existing descriptor Id will cause error. " +
+            "Omit this field to create new descriptor." )
+    @Override
+    public ComponentDescriptorId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "Timestamp of the descriptor creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
+
     @Override
     public String getSearchText() {
         return name;
     }
 
-
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -84,4 +107,5 @@ public class ComponentDescriptor extends SearchTextBased<ComponentDescriptorId>
         result = 31 * result + (actions != null ? actions.hashCode() : 0);
         return result;
     }
+
 }