Added Swagger API documentation for Edge Controller

Volodymyr Babak
1 parent e6e05c9b
Showing 1 changed file with 57 additions and 1 deletions
application/src/main/java/org/thingsboard/server/controller/EdgeController.java
--- a/application/src/main/java/org/thingsboard/server/controller/EdgeController.java
View file @8e0b76f
+++ b/application/src/main/java/org/thingsboard/server/controller/EdgeController.java
View file @8e0b76f
@@ -17,6 +17,7 @@ package org.thingsboard.server.controller;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.google.common.util.concurrent.ListenableFuture;
+import io.swagger.annotations.ApiOperation;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatus;
@@ -75,6 +76,8 @@ public class EdgeController extends BaseController {
     private final EdgeBulkImportService edgeBulkImportService;
     public static final String EDGE_ID = "edgeId";
+    public static final String EDGE_SECURITY_CHECK = "If the user has the authority of 'Tenant Administrator', the server checks that the edge is owned by the same tenant. " +
+            "If the user has the authority of 'Customer User', the server checks that the edge is assigned to the same customer.";
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edges/enabled", method = RequestMethod.GET)
@@ -83,6 +86,8 @@ public class EdgeController extends BaseController {
         return edgesEnabled;
     }
+    @ApiOperation(value = "Get Edge (getEdgeById)",
+            notes = "Get the Edge object based on the provided Edge Id. " + EDGE_SECURITY_CHECK)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edge/{edgeId}", method = RequestMethod.GET)
     @ResponseBody
@@ -100,6 +105,8 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Edge Info (getEdgeInfoById)",
+            notes = "Get the Edge Info object based on the provided Edge Id. " + EDGE_SECURITY_CHECK)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edge/info/{edgeId}", method = RequestMethod.GET)
     @ResponseBody
@@ -117,6 +124,10 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Create Or Update Edge (saveEdge)",
+            notes = "Creates or Updates the Edge. Platform generates random Edge Id during edge creation. " +
+                    "The edge id will be present in the response. " +
+                    "Specify the Edge id when you would like to update the edge. Referencing non-existing edge Id will cause an error.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge", method = RequestMethod.POST)
     @ResponseBody
@@ -163,6 +174,8 @@ public class EdgeController extends BaseController {
         logEntityAction(edge.getId(), edge, null, updated ? ActionType.UPDATED : ActionType.ADDED, null);
     }
+    @ApiOperation(value = "Delete edge (deleteEdge)",
+            notes = "Deletes the edge. Referencing non-existing edge Id will cause an error.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge/{edgeId}", method = RequestMethod.DELETE)
     @ResponseStatus(value = HttpStatus.OK)
@@ -191,6 +204,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Tenant Edges (getEdges)",
+            notes = "Returns a page of edges owned by tenant. " +
+                    PAGE_DATA_PARAMETERS)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
@@ -208,6 +224,8 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Assign edge to customer (assignEdgeToCustomer)",
+            notes = "Creates assignment of the edge to customer. Customer will be able to query edge afterwards.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/customer/{customerId}/edge/{edgeId}", method = RequestMethod.POST)
     @ResponseBody
@@ -243,6 +261,8 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Unassign edge from customer (unassignEdgeFromCustomer)",
+            notes = "Clears assignment of the edge to customer. Customer will not be able to query edge afterwards.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/customer/edge/{edgeId}", method = RequestMethod.DELETE)
     @ResponseBody
@@ -277,6 +297,10 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Make edge publicly available (assignEdgeToPublicCustomer)",
+            notes = "Edge will be available for non-authorized (not logged-in) users. " +
+                    "This is useful to create dashboards that you plan to share/embed on a publicly available website. " +
+                    "However, users that are logged-in and belong to different tenant will not be able to access the edge.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/customer/public/edge/{edgeId}", method = RequestMethod.POST)
     @ResponseBody
@@ -304,6 +328,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Tenant Edges (getTenantEdges)",
+            notes = "Returns a page of edges owned by tenant. " +
+                    PAGE_DATA_PARAMETERS)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
@@ -327,6 +354,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Tenant Edge Infos (getTenantEdgeInfos)",
+            notes = "Returns a page of edges info objects owned by tenant. " +
+                    PAGE_DATA_PARAMETERS + DEVICE_INFO_DESCRIPTION)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/edgeInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
@@ -350,6 +380,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Tenant Edge (getTenantEdge)",
+            notes = "Requested edge must be owned by tenant or customer that the user belongs to. " +
+                    "Edge name is an unique property of edge. So it can be used to identify the edge.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/tenant/edges", params = {"edgeName"}, method = RequestMethod.GET)
     @ResponseBody
@@ -362,6 +395,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Set root rule chain for provided edge (setRootRuleChain)",
+            notes = "Change root rule chain of the edge from the current to the new provided rule chain. \n" +
+                    "This operation will send an notification to remote edge service to update root rule chain remotely.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge/{edgeId}/{ruleChainId}/root", method = RequestMethod.POST)
     @ResponseBody
@@ -394,6 +430,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Customer Edges (getCustomerEdges)",
+            notes = "Returns a page of edges objects assigned to customer. " +
+                    PAGE_DATA_PARAMETERS)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/customer/{customerId}/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
@@ -429,6 +468,9 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Customer Edge Infos (getCustomerEdgeInfos)",
+            notes = "Returns a page of edges info objects assigned to customer. " +
+                    PAGE_DATA_PARAMETERS + DEVICE_INFO_DESCRIPTION)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/customer/{customerId}/edgeInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
@@ -464,6 +506,8 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Edges By Ids (getEdgesByIds)",
+            notes = "Requested edges must be owned by tenant or assigned to customer which user is performing the request. ")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edges", params = {"edgeIds"}, method = RequestMethod.GET)
     @ResponseBody
@@ -496,6 +540,10 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Find related edges (findByQuery)",
+            notes = "Returns all edges that are related to the specific entity. " +
+                    "The entity id, relation type, device types, depth of the search, and other query parameters defined using complex 'EdgeSearchQuery' object. " +
+                    "See 'Model' tab of the Parameters for more info.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edges", method = RequestMethod.POST)
     @ResponseBody
@@ -527,6 +575,8 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get Edge Types (getEdgeTypes)",
+            notes = "Returns a set of unique edge types based on edges that are either owned by the tenant or assigned to the customer which user is performing the request.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/edge/types", method = RequestMethod.GET)
     @ResponseBody
@@ -541,6 +591,8 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Sync edge (syncEdge)",
+            notes = "Starts synchronization process between edge and cloud - all entities that are assigned to particular edge are going to be send to remote edge service.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge/sync/{edgeId}", method = RequestMethod.POST)
     public void syncEdge(@PathVariable("edgeId") String strEdgeId) throws ThingsboardException {
@@ -560,6 +612,8 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Find missing rule chains (findMissingToRelatedRuleChains)",
+            notes = "Returns list of rule chains IDs that are not assigned to particular edge, but these rule chains are present in the already assigned rule chains to edge")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge/missingToRelatedRuleChains/{edgeId}", method = RequestMethod.GET)
     @ResponseBody
@@ -575,9 +629,11 @@ public class EdgeController extends BaseController {
         }
     }
+    @ApiOperation(value = "Import the bulk of edges (processEdgesBulkImport)",
+            notes = "There's an ability to import the bulk of edges using the only .csv file.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @PostMapping("/edge/bulk_import")
-    public BulkImportResult<Edge> processEdgeBulkImport(@RequestBody BulkImportRequest request) throws Exception {
+    public BulkImportResult<Edge> processEdgesBulkImport(@RequestBody BulkImportRequest request) throws Exception {
         SecurityUser user = getCurrentUser();
         RuleChain edgeTemplateRootRuleChain = ruleChainService.getEdgeTemplateRootRuleChain(user.getTenantId());
         if (edgeTemplateRootRuleChain == null) {