Edge Swagger docs - part 2

Volodymyr Babak
1 parent 004df832
Showing 7 changed files with 133 additions and 19 deletions
application/src/main/java/org/thingsboard/server/controller/ControllerConstants.java
application/src/main/java/org/thingsboard/server/controller/DashboardController.java
application/src/main/java/org/thingsboard/server/controller/EdgeController.java
application/src/main/java/org/thingsboard/server/controller/RuleChainController.java
common/data/src/main/java/org/thingsboard/server/common/data/edge/Edge.java
common/data/src/main/java/org/thingsboard/server/common/data/edge/EdgeSearchQuery.java
ui-ngx/src/assets/locale/locale.constant-de_DE.json
--- a/application/src/main/java/org/thingsboard/server/controller/ControllerConstants.java
View file @0635929
+++ b/application/src/main/java/org/thingsboard/server/controller/ControllerConstants.java
View file @0635929
@@ -23,6 +23,7 @@ public class ControllerConstants {
     protected static final String CUSTOMER_ID = "customerId";
     protected static final String TENANT_ID = "tenantId";
     protected static final String DEVICE_ID = "deviceId";
+    protected static final String EDGE_ID = "edgeId";
     protected static final String RPC_ID = "rpcId";
     protected static final String ENTITY_ID = "entityId";
     protected static final String PAGE_DATA_PARAMETERS = "You can specify parameters to filter the results. " +
--- a/application/src/main/java/org/thingsboard/server/controller/DashboardController.java
View file @0635929
+++ b/application/src/main/java/org/thingsboard/server/controller/DashboardController.java
View file @0635929
@@ -51,7 +51,6 @@ import org.thingsboard.server.common.data.id.EdgeId;
 import org.thingsboard.server.common.data.id.TenantId;
 import org.thingsboard.server.common.data.page.PageData;
 import org.thingsboard.server.common.data.page.PageLink;
-import org.thingsboard.server.common.data.page.TimePageLink;
 import org.thingsboard.server.queue.util.TbCoreComponent;
 import org.thingsboard.server.service.security.model.SecurityUser;
 import org.thingsboard.server.service.security.permission.Operation;
@@ -69,6 +68,8 @@ import static org.thingsboard.server.controller.ControllerConstants.DASHBOARD_SO
 import static org.thingsboard.server.controller.ControllerConstants.DASHBOARD_TEXT_SEARCH_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_ASYNC_FIRST_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_RECEIVE_STEP_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.EDGE_ID;
+import static org.thingsboard.server.controller.ControllerConstants.EDGE_ID_PARAM_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_UNASSIGN_ASYNC_FIRST_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_UNASSIGN_RECEIVE_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.PAGE_DATA_PARAMETERS;
@@ -906,24 +907,32 @@ public class DashboardController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Edge Dashboards (getEdgeDashboards)",
+        notes = "Returns a page of dashboard info objects assigned to the specified edge. "
+                + DASHBOARD_INFO_DEFINITION + " " + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
+        produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edge/{edgeId}/dashboards", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
     public PageData<DashboardInfo> getEdgeDashboards(
-            @PathVariable("edgeId") String strEdgeId,
+            @ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
+            @PathVariable(EDGE_ID) String strEdgeId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
+            @ApiParam(value = DASHBOARD_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = DASHBOARD_SORT_PROPERTY_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortProperty,
-            @RequestParam(required = false) String sortOrder,
-            @RequestParam(required = false) Long startTime,
-            @RequestParam(required = false) Long endTime) throws ThingsboardException {
+            @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
+            @RequestParam(required = false) String sortOrder) throws ThingsboardException {
         checkParameter("edgeId", strEdgeId);
         try {
             TenantId tenantId = getCurrentUser().getTenantId();
             EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
             checkEdgeId(edgeId, Operation.READ);
-            TimePageLink pageLink = createTimePageLink(pageSize, page, textSearch, sortProperty, sortOrder, startTime, endTime);
+            PageLink pageLink = createPageLink(pageSize, page, textSearch, sortProperty, sortOrder);
             PageData<DashboardInfo> nonFilteredResult = dashboardService.findDashboardsByTenantIdAndEdgeId(tenantId, edgeId, pageLink);
             List<DashboardInfo> filteredDashboards = nonFilteredResult.getData().stream().filter(dashboardInfo -> {
                 try {
--- a/application/src/main/java/org/thingsboard/server/controller/EdgeController.java
View file @0635929
+++ b/application/src/main/java/org/thingsboard/server/controller/EdgeController.java
View file @0635929
@@ -452,17 +452,17 @@ public class EdgeController extends BaseController {
         }
     }
-    @ApiOperation(value = "Set root rule chain for provided edge (setRootRuleChain)",
+    @ApiOperation(value = "Set root rule chain for provided edge (setEdgeRootRuleChain)",
             notes = "Change root rule chain of the edge to the new provided rule chain. \n" +
                     "This operation will send a notification to update root rule chain on remote edge service." + TENANT_AUTHORITY_PARAGRAPH,
             produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge/{edgeId}/{ruleChainId}/root", method = RequestMethod.POST)
     @ResponseBody
-    public Edge setRootRuleChain(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
-                                 @PathVariable(EDGE_ID) String strEdgeId,
-                                 @ApiParam(value = RULE_CHAIN_ID_PARAM_DESCRIPTION, required = true)
-                                 @PathVariable("ruleChainId") String strRuleChainId) throws ThingsboardException {
+    public Edge setEdgeRootRuleChain(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
+                                     @PathVariable(EDGE_ID) String strEdgeId,
+                                     @ApiParam(value = RULE_CHAIN_ID_PARAM_DESCRIPTION, required = true)
+                                     @PathVariable("ruleChainId") String strRuleChainId) throws ThingsboardException {
         checkParameter(EDGE_ID, strEdgeId);
         checkParameter("ruleChainId", strRuleChainId);
         try {
@@ -736,6 +736,9 @@ public class EdgeController extends BaseController {
         edge.setEdgeLicenseKey(null);
     }
+    @ApiOperation(value = "Check edge license (checkInstance)",
+            notes = "Checks license request from edge service by forwarding request to license portal.",
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/license/checkInstance", method = RequestMethod.POST)
     @ResponseBody
     public ResponseEntity<JsonNode> checkInstance(@RequestBody JsonNode request) throws ThingsboardException {
@@ -748,6 +751,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Activate edge instance (activateInstance)",
+            notes = "Activates edge license on license portal.",
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @RequestMapping(value = "/license/activateInstance", params = {"licenseSecret", "releaseDate"}, method = RequestMethod.POST)
     @ResponseBody
     public ResponseEntity<JsonNode> activateInstance(@RequestParam String licenseSecret,
--- a/application/src/main/java/org/thingsboard/server/controller/RuleChainController.java
View file @0635929
+++ b/application/src/main/java/org/thingsboard/server/controller/RuleChainController.java
View file @0635929
@@ -83,6 +83,8 @@ import java.util.stream.Collectors;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_ASYNC_FIRST_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_ASSIGN_RECEIVE_STEP_DESCRIPTION;
+import static org.thingsboard.server.controller.ControllerConstants.EDGE_ID;
+import static org.thingsboard.server.controller.ControllerConstants.EDGE_ID_PARAM_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_UNASSIGN_ASYNC_FIRST_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.EDGE_UNASSIGN_RECEIVE_STEP_DESCRIPTION;
 import static org.thingsboard.server.controller.ControllerConstants.MARKDOWN_CODE_BLOCK_END;
@@ -676,17 +678,25 @@ public class RuleChainController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Edge Rule Chains (getEdgeRuleChains)",
+        notes = "Returns a page of Rule Chains assigned to the specified edge. " + RULE_CHAIN_DESCRIPTION + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge/{edgeId}/ruleChains", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
     public PageData<RuleChain> getEdgeRuleChains(
-            @PathVariable("edgeId") String strEdgeId,
+            @ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
+            @PathVariable(EDGE_ID) String strEdgeId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
+            @ApiParam(value = RULE_CHAIN_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = RULE_CHAIN_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 {
-        checkParameter("edgeId", strEdgeId);
+        checkParameter(EDGE_ID, strEdgeId);
         try {
             TenantId tenantId = getCurrentUser().getTenantId();
             EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
@@ -698,10 +708,14 @@ public class RuleChainController extends BaseController {
         }
     }
+    @ApiOperation(value = "Set Edge Template Root Rule Chain (setEdgeTemplateRootRuleChain)",
+            notes = "Makes the rule chain to be root rule chain for any new edge that will be created. " +
+                    "Does not update root rule chain for already created edges. " + TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/ruleChain/{ruleChainId}/edgeTemplateRoot", method = RequestMethod.POST)
     @ResponseBody
-    public RuleChain setEdgeTemplateRootRuleChain(@PathVariable(RULE_CHAIN_ID) String strRuleChainId) throws ThingsboardException {
+    public RuleChain setEdgeTemplateRootRuleChain(@ApiParam(value = RULE_CHAIN_ID_PARAM_DESCRIPTION)
+                                                  @PathVariable(RULE_CHAIN_ID) String strRuleChainId) throws ThingsboardException {
         checkParameter(RULE_CHAIN_ID, strRuleChainId);
         try {
             RuleChainId ruleChainId = new RuleChainId(toUUID(strRuleChainId));
@@ -717,10 +731,14 @@ public class RuleChainController extends BaseController {
         }
     }
+    @ApiOperation(value = "Set Auto Assign To Edge Rule Chain (setAutoAssignToEdgeRuleChain)",
+            notes = "Makes the rule chain to be automatically assigned for any new edge that will be created. " +
+                    "Does not assign this rule chain for already created edges. " + TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/ruleChain/{ruleChainId}/autoAssignToEdge", method = RequestMethod.POST)
     @ResponseBody
-    public RuleChain setAutoAssignToEdgeRuleChain(@PathVariable(RULE_CHAIN_ID) String strRuleChainId) throws ThingsboardException {
+    public RuleChain setAutoAssignToEdgeRuleChain(@ApiParam(value = RULE_CHAIN_ID_PARAM_DESCRIPTION)
+                                                  @PathVariable(RULE_CHAIN_ID) String strRuleChainId) throws ThingsboardException {
         checkParameter(RULE_CHAIN_ID, strRuleChainId);
         try {
             RuleChainId ruleChainId = new RuleChainId(toUUID(strRuleChainId));
@@ -736,10 +754,14 @@ public class RuleChainController extends BaseController {
         }
     }
+    @ApiOperation(value = "Unset Auto Assign To Edge Rule Chain (unsetAutoAssignToEdgeRuleChain)",
+            notes = "Removes the rule chain from the list of rule chains that are going to be automatically assigned for any new edge that will be created. " +
+                    "Does not unassign this rule chain for already assigned edges. " + TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/ruleChain/{ruleChainId}/autoAssignToEdge", method = RequestMethod.DELETE)
     @ResponseBody
-    public RuleChain unsetAutoAssignToEdgeRuleChain(@PathVariable(RULE_CHAIN_ID) String strRuleChainId) throws ThingsboardException {
+    public RuleChain unsetAutoAssignToEdgeRuleChain(@ApiParam(value = RULE_CHAIN_ID_PARAM_DESCRIPTION)
+                                                    @PathVariable(RULE_CHAIN_ID) String strRuleChainId) throws ThingsboardException {
         checkParameter(RULE_CHAIN_ID, strRuleChainId);
         try {
             RuleChainId ruleChainId = new RuleChainId(toUUID(strRuleChainId));
@@ -756,6 +778,8 @@ public class RuleChainController extends BaseController {
     }
     // TODO: @voba refactor this - add new config to edge rule chain to set it as auto-assign
+    @ApiOperation(value = "Get Auto Assign To Edge Rule Chains (getAutoAssignToEdgeRuleChains)",
+            notes = "Returns a list of Rule Chains that will be assigned to a newly created edge. " + RULE_CHAIN_DESCRIPTION + TENANT_AUTHORITY_PARAGRAPH)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/ruleChain/autoAssignToEdgeRuleChains", method = RequestMethod.GET)
     @ResponseBody
--- a/common/data/src/main/java/org/thingsboard/server/common/data/edge/Edge.java
View file @0635929
+++ b/common/data/src/main/java/org/thingsboard/server/common/data/edge/Edge.java
View file @0635929
@@ -15,8 +15,9 @@
  */
 package org.thingsboard.server.common.data.edge;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.EqualsAndHashCode;
-import lombok.Getter;
 import lombok.Setter;
 import lombok.ToString;
 import org.thingsboard.server.common.data.HasCustomerId;
@@ -28,9 +29,9 @@ import org.thingsboard.server.common.data.id.EdgeId;
 import org.thingsboard.server.common.data.id.RuleChainId;
 import org.thingsboard.server.common.data.id.TenantId;
+@ApiModel
 @EqualsAndHashCode(callSuper = true)
 @ToString
-@Getter
 @Setter
 public class Edge extends SearchTextBasedWithAdditionalInfo<EdgeId> implements HasName, HasTenantId, HasCustomerId {
@@ -82,8 +83,77 @@ public class Edge extends SearchTextBasedWithAdditionalInfo<EdgeId> implements H
         this.cloudEndpoint = edge.getCloudEndpoint();
     }
+    @ApiModelProperty(position = 1, value = "JSON object with the Edge Id. " +
+            "Specify this field to update the Edge. " +
+            "Referencing non-existing Edge Id will cause error. " +
+            "Omit this field to create new Edge." )
+    @Override
+    public EdgeId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "Timestamp of the edge creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
+
+    @ApiModelProperty(position = 3, value = "JSON object with Tenant Id. Use 'assignDeviceToTenant' to change the Tenant Id.", readOnly = true)
+    @Override
+    public TenantId getTenantId() {
+        return this.tenantId;
+    }
+
+    @ApiModelProperty(position = 4, value = "JSON object with Customer Id. Use 'assignEdgeToCustomer' to change the Customer Id.", readOnly = true)
+    @Override
+    public CustomerId getCustomerId() {
+        return this.customerId;
+    }
+
+    @ApiModelProperty(position = 5, value = "JSON object with Root Rule Chain Id. Use 'setEdgeRootRuleChain' to change the Root Rule Chain Id.", readOnly = true)
+    public RuleChainId getRootRuleChainId() {
+        return this.rootRuleChainId;
+    }
+
+    @ApiModelProperty(position = 6, required = true, value = "Unique Edge Name in scope of Tenant", example = "Silo_A_Edge")
+    @Override
+    public String getName() {
+        return this.name;
+    }
+
+    @ApiModelProperty(position = 7, required = true, value = "Edge type", example = "Silos")
+    public String getType() {
+        return this.type;
+    }
+
+    @ApiModelProperty(position = 8, value = "Label that may be used in widgets", example = "Silo Edge on far field")
+    public String getLabel() {
+        return this.label;
+    }
+
     @Override
     public String getSearchText() {
         return getName();
     }
+
+    @ApiModelProperty(position = 9, required = true, value = "Edge routing key ('username') to authorize on cloud")
+    public String getRoutingKey() {
+        return this.routingKey;
+    }
+
+    @ApiModelProperty(position = 10, required = true, value = "Edge secret ('password') to authorize on cloud")
+    public String getSecret() {
+        return this.secret;
+    }
+
+    @ApiModelProperty(position = 11, required = true, value = "Edge license key obtained from license portal", example = "AgcnI24Z06XC&m6Sxsdgf")
+    public String getEdgeLicenseKey() {
+        return this.edgeLicenseKey;
+    }
+
+    @ApiModelProperty(position = 12, required = true, value = "Edge uses this cloud URL to activate and periodically check it's license", example = "https://thingsboard.cloud")
+    public String getCloudEndpoint() {
+        return this.cloudEndpoint;
+    }
+
 }
--- a/common/data/src/main/java/org/thingsboard/server/common/data/edge/EdgeSearchQuery.java
View file @0635929
+++ b/common/data/src/main/java/org/thingsboard/server/common/data/edge/EdgeSearchQuery.java
View file @0635929
@@ -15,6 +15,7 @@
  */
 package org.thingsboard.server.common.data.edge;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.EntityType;
 import org.thingsboard.server.common.data.relation.EntityRelation;
@@ -28,8 +29,11 @@ import java.util.List;
 @Data
 public class EdgeSearchQuery {
+    @ApiModelProperty(position = 3, value = "Main search parameters.")
     private RelationsSearchParameters parameters;
+    @ApiModelProperty(position = 1, value = "Type of the relation between root entity and edge (e.g. 'Contains' or 'Manages').")
     private String relationType;
+    @ApiModelProperty(position = 2, value = "Array of edge types to filter the related entities (e.g. 'Silos', 'Stores').")
     private List<String> edgeTypes;
     public EntityRelationsQuery toEntitySearchQuery() {
--- a/ui-ngx/src/assets/locale/locale.constant-de_DE.json
View file @0635929
+++ b/ui-ngx/src/assets/locale/locale.constant-de_DE.json
View file @0635929
@@ -737,7 +737,7 @@
     "close": "Dialog schließen"
   },
   "edge": {
-    "edge": "Rand",
+    "edge": "Edge",
     "edge-instances": "Kanteninstanzen",
     "edge-file": "Edge-Datei",
     "management": "Rand verwalten",