简柏林 / thingskit · Commits

Commit 11447ac4f6ee4dcad2a3cca1d59a6ab7b4bb8e2a

Authored by Andrew Shvayka
Committed by GitHub
2 parents 4783d7dd 62643711

Merge pull request #5356 from volodymyr-babak/feature/swagger-edge-controller 

Added Swagger API documentation for Edge Controller
Inline Side-by-side
Showing 6 changed files with 163 additions and 18 deletions
... ... @@ -173,16 +173,19 @@ public abstract class BaseController {
173 173 public static final String ALARM_ID_PARAM_DESCRIPTION = "A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
174 174 public static final String ENTITY_ID_PARAM_DESCRIPTION = "A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
175 175 public static final String ENTITY_TYPE_PARAM_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'";
  176 + public static final String RULE_CHAIN_ID_PARAM_DESCRIPTION = "A string value representing the rule chain id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
176 177
177 178 protected final String PAGE_SIZE_DESCRIPTION = "Maximum amount of entities in a one page";
178 179 protected final String PAGE_NUMBER_DESCRIPTION = "Sequence number of page starting from 0";
179 180 protected final String DEVICE_TYPE_DESCRIPTION = "Device type as the name of the device profile";
180 181 protected final String ASSET_TYPE_DESCRIPTION = "Asset type";
  182 + protected final String EDGE_TYPE_DESCRIPTION = "A string value representing the edge type. For example, 'default'";
181 183
182 184 protected final String ASSET_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the asset name.";
183 185 protected final String DASHBOARD_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the dashboard title.";
184 186 protected final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device name.";
185 187 protected final String CUSTOMER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the customer title.";
  188 + protected final String EDGE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the edge name.";
186 189 protected final String EVENT_TEXT_SEARCH_DESCRIPTION = "The value is not used in searching.";
187 190 protected final String SORT_PROPERTY_DESCRIPTION = "Property of entity to sort by";
188 191 protected final String DASHBOARD_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title";
... ... @@ -191,12 +194,14 @@ public abstract class BaseController {
191 194 protected final String ASSET_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
192 195 protected final String ALARM_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, startTs, endTs, type, ackTs, clearTs, severity, status";
193 196 protected final String EVENT_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, id";
  197 + protected final String EDGE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
194 198 protected final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESC (DESCENDING)";
195 199 protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
196 200 protected final String DEVICE_INFO_DESCRIPTION = "Device Info is an extension of the default Device object that contains information about the assigned customer name and device profile name. ";
197 201 protected final String ASSET_INFO_DESCRIPTION = "Asset Info is an extension of the default Asset object that contains information about the assigned customer name. ";
198 202 protected final String ALARM_INFO_DESCRIPTION = "Alarm Info is an extension of the default Alarm object that also contains name of the alarm originator.";
199 203 protected final String RELATION_INFO_DESCRIPTION = "Relation Info is an extension of the default Relation object that contains information about the 'from' and 'to' entity names. ";
  204 + protected final String EDGE_INFO_DESCRIPTION = "Edge Info is an extension of the default Edge object that contains information about the assigned customer name. ";
200 205
201 206 protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name.";
202 207 protected final String ASSET_NAME_DESCRIPTION = "A string value representing the Asset name.";
... ...
... ... @@ -17,9 +17,12 @@ package org.thingsboard.server.controller;
17 17
18 18 import com.fasterxml.jackson.databind.JsonNode;
19 19 import com.google.common.util.concurrent.ListenableFuture;
  20 +import io.swagger.annotations.ApiOperation;
  21 +import io.swagger.annotations.ApiParam;
20 22 import lombok.RequiredArgsConstructor;
21 23 import lombok.extern.slf4j.Slf4j;
22 24 import org.springframework.http.HttpStatus;
  25 +import org.springframework.http.MediaType;
23 26 import org.springframework.http.ResponseEntity;
24 27 import org.springframework.security.access.prepost.PreAuthorize;
25 28 import org.springframework.web.bind.annotation.PathVariable;
... ... @@ -75,7 +78,11 @@ public class EdgeController extends BaseController {
75 78 private final EdgeBulkImportService edgeBulkImportService;
76 79
77 80 public static final String EDGE_ID = "edgeId";
  81 + 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. " +
  82 + "If the user has the authority of 'Customer User', the server checks that the edge is assigned to the same customer.";
78 83
  84 + @ApiOperation(value = "Is edges support enabled (isEdgesSupportEnabled)",
  85 + notes = "Returns 'true' if edges support enabled on server, 'false' - otherwise.")
79 86 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
80 87 @RequestMapping(value = "/edges/enabled", method = RequestMethod.GET)
81 88 @ResponseBody
... ... @@ -83,10 +90,14 @@ public class EdgeController extends BaseController {
83 90 return edgesEnabled;
84 91 }
85 92
  93 + @ApiOperation(value = "Get Edge (getEdgeById)",
  94 + notes = "Get the Edge object based on the provided Edge Id. " + EDGE_SECURITY_CHECK,
  95 + produces = MediaType.APPLICATION_JSON_VALUE)
86 96 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
87 97 @RequestMapping(value = "/edge/{edgeId}", method = RequestMethod.GET)
88 98 @ResponseBody
89   - public Edge getEdgeById(@PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
  99 + public Edge getEdgeById(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  100 + @PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
90 101 checkParameter(EDGE_ID, strEdgeId);
91 102 try {
92 103 EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
... ... @@ -100,10 +111,14 @@ public class EdgeController extends BaseController {
100 111 }
101 112 }
102 113
  114 + @ApiOperation(value = "Get Edge Info (getEdgeInfoById)",
  115 + notes = "Get the Edge Info object based on the provided Edge Id. " + EDGE_SECURITY_CHECK,
  116 + produces = MediaType.APPLICATION_JSON_VALUE)
103 117 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
104 118 @RequestMapping(value = "/edge/info/{edgeId}", method = RequestMethod.GET)
105 119 @ResponseBody
106   - public EdgeInfo getEdgeInfoById(@PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
  120 + public EdgeInfo getEdgeInfoById(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  121 + @PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
107 122 checkParameter(EDGE_ID, strEdgeId);
108 123 try {
109 124 EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
... ... @@ -117,10 +132,18 @@ public class EdgeController extends BaseController {
117 132 }
118 133 }
119 134
  135 + @ApiOperation(value = "Create Or Update Edge (saveEdge)",
  136 + notes = "Create or update the Edge. When creating edge, platform generates Edge Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
  137 + "The newly created edge id will be present in the response. " +
  138 + "Specify existing Edge id to update the edge. " +
  139 + "Referencing non-existing Edge Id will cause 'Not Found' error." +
  140 + "\n\nEdge name is unique in the scope of tenant. Use unique identifiers like MAC or IMEI for the edge names and non-unique 'label' field for user-friendly visualization purposes.",
  141 + produces = MediaType.APPLICATION_JSON_VALUE)
120 142 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
121 143 @RequestMapping(value = "/edge", method = RequestMethod.POST)
122 144 @ResponseBody
123   - public Edge saveEdge(@RequestBody Edge edge) throws ThingsboardException {
  145 + public Edge saveEdge(@ApiParam(value = "A JSON value representing the ed.", required = true)
  146 + @RequestBody Edge edge) throws ThingsboardException {
124 147 try {
125 148 TenantId tenantId = getCurrentUser().getTenantId();
126 149 edge.setTenantId(tenantId);
... ... @@ -163,10 +186,13 @@ public class EdgeController extends BaseController {
163 186 logEntityAction(edge.getId(), edge, null, updated ? ActionType.UPDATED : ActionType.ADDED, null);
164 187 }
165 188
  189 + @ApiOperation(value = "Delete edge (deleteEdge)",
  190 + notes = "Deletes the edge. Referencing non-existing edge Id will cause an error.")
166 191 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
167 192 @RequestMapping(value = "/edge/{edgeId}", method = RequestMethod.DELETE)
168 193 @ResponseStatus(value = HttpStatus.OK)
169   - public void deleteEdge(@PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
  194 + public void deleteEdge(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  195 + @PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
170 196 checkParameter(EDGE_ID, strEdgeId);
171 197 try {
172 198 EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
... ... @@ -191,13 +217,21 @@ public class EdgeController extends BaseController {
191 217 }
192 218 }
193 219
  220 + @ApiOperation(value = "Get Tenant Edges (getEdges)",
  221 + notes = "Returns a page of edges owned by tenant. " +
  222 + PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
194 223 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
195 224 @RequestMapping(value = "/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
196 225 @ResponseBody
197   - public PageData<Edge> getEdges(@RequestParam int pageSize,
  226 + public PageData<Edge> getEdges(@ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
  227 + @RequestParam int pageSize,
  228 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
198 229 @RequestParam int page,
  230 + @ApiParam(value = EDGE_TEXT_SEARCH_DESCRIPTION)
199 231 @RequestParam(required = false) String textSearch,
  232 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EDGE_SORT_PROPERTY_ALLOWABLE_VALUES)
200 233 @RequestParam(required = false) String sortProperty,
  234 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
201 235 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
202 236 try {
203 237 PageLink pageLink = createPageLink(pageSize, page, textSearch, sortProperty, sortOrder);
... ... @@ -208,10 +242,15 @@ public class EdgeController extends BaseController {
208 242 }
209 243 }
210 244
  245 + @ApiOperation(value = "Assign edge to customer (assignEdgeToCustomer)",
  246 + notes = "Creates assignment of the edge to customer. Customer will be able to query edge afterwards.",
  247 + produces = MediaType.APPLICATION_JSON_VALUE)
211 248 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
212 249 @RequestMapping(value = "/customer/{customerId}/edge/{edgeId}", method = RequestMethod.POST)
213 250 @ResponseBody
214   - public Edge assignEdgeToCustomer(@PathVariable("customerId") String strCustomerId,
  251 + public Edge assignEdgeToCustomer(@ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION, required = true)
  252 + @PathVariable("customerId") String strCustomerId,
  253 + @ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
215 254 @PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
216 255 checkParameter("customerId", strCustomerId);
217 256 checkParameter(EDGE_ID, strEdgeId);
... ... @@ -243,10 +282,14 @@ public class EdgeController extends BaseController {
243 282 }
244 283 }
245 284
  285 + @ApiOperation(value = "Unassign edge from customer (unassignEdgeFromCustomer)",
  286 + notes = "Clears assignment of the edge to customer. Customer will not be able to query edge afterwards.",
  287 + produces = MediaType.APPLICATION_JSON_VALUE)
246 288 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
247 289 @RequestMapping(value = "/customer/edge/{edgeId}", method = RequestMethod.DELETE)
248 290 @ResponseBody
249   - public Edge unassignEdgeFromCustomer(@PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
  291 + public Edge unassignEdgeFromCustomer(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  292 + @PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
250 293 checkParameter(EDGE_ID, strEdgeId);
251 294 try {
252 295 EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
... ... @@ -277,10 +320,16 @@ public class EdgeController extends BaseController {
277 320 }
278 321 }
279 322
  323 + @ApiOperation(value = "Make edge publicly available (assignEdgeToPublicCustomer)",
  324 + notes = "Edge will be available for non-authorized (not logged-in) users. " +
  325 + "This is useful to create dashboards that you plan to share/embed on a publicly available website. " +
  326 + "However, users that are logged-in and belong to different tenant will not be able to access the edge.",
  327 + produces = MediaType.APPLICATION_JSON_VALUE)
280 328 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
281 329 @RequestMapping(value = "/customer/public/edge/{edgeId}", method = RequestMethod.POST)
282 330 @ResponseBody
283   - public Edge assignEdgeToPublicCustomer(@PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
  331 + public Edge assignEdgeToPublicCustomer(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  332 + @PathVariable(EDGE_ID) String strEdgeId) throws ThingsboardException {
284 333 checkParameter(EDGE_ID, strEdgeId);
285 334 try {
286 335 EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
... ... @@ -304,15 +353,24 @@ public class EdgeController extends BaseController {
304 353 }
305 354 }
306 355
  356 + @ApiOperation(value = "Get Tenant Edges (getTenantEdges)",
  357 + notes = "Returns a page of edges owned by tenant. " +
  358 + PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
307 359 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
308 360 @RequestMapping(value = "/tenant/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
309 361 @ResponseBody
310 362 public PageData<Edge> getTenantEdges(
  363 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
311 364 @RequestParam int pageSize,
  365 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
312 366 @RequestParam int page,
  367 + @ApiParam(value = EDGE_TYPE_DESCRIPTION)
313 368 @RequestParam(required = false) String type,
  369 + @ApiParam(value = EDGE_TEXT_SEARCH_DESCRIPTION)
314 370 @RequestParam(required = false) String textSearch,
  371 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EDGE_SORT_PROPERTY_ALLOWABLE_VALUES)
315 372 @RequestParam(required = false) String sortProperty,
  373 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
316 374 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
317 375 try {
318 376 TenantId tenantId = getCurrentUser().getTenantId();
... ... @@ -327,15 +385,25 @@ public class EdgeController extends BaseController {
327 385 }
328 386 }
329 387
  388 + @ApiOperation(value = "Get Tenant Edge Infos (getTenantEdgeInfos)",
  389 + notes = "Returns a page of edges info objects owned by tenant. " +
  390 + PAGE_DATA_PARAMETERS + EDGE_INFO_DESCRIPTION,
  391 + produces = MediaType.APPLICATION_JSON_VALUE)
330 392 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
331 393 @RequestMapping(value = "/tenant/edgeInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
332 394 @ResponseBody
333 395 public PageData<EdgeInfo> getTenantEdgeInfos(
  396 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
334 397 @RequestParam int pageSize,
  398 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
335 399 @RequestParam int page,
  400 + @ApiParam(value = EDGE_TYPE_DESCRIPTION)
336 401 @RequestParam(required = false) String type,
  402 + @ApiParam(value = EDGE_TEXT_SEARCH_DESCRIPTION)
337 403 @RequestParam(required = false) String textSearch,
  404 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EDGE_SORT_PROPERTY_ALLOWABLE_VALUES)
338 405 @RequestParam(required = false) String sortProperty,
  406 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
339 407 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
340 408 try {
341 409 TenantId tenantId = getCurrentUser().getTenantId();
... ... @@ -350,10 +418,15 @@ public class EdgeController extends BaseController {
350 418 }
351 419 }
352 420
  421 + @ApiOperation(value = "Get Tenant Edge (getTenantEdge)",
  422 + notes = "Requested edge must be owned by tenant or customer that the user belongs to. " +
  423 + "Edge name is an unique property of edge. So it can be used to identify the edge.",
  424 + produces = MediaType.APPLICATION_JSON_VALUE)
353 425 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
354 426 @RequestMapping(value = "/tenant/edges", params = {"edgeName"}, method = RequestMethod.GET)
355 427 @ResponseBody
356   - public Edge getTenantEdge(@RequestParam String edgeName) throws ThingsboardException {
  428 + public Edge getTenantEdge(@ApiParam(value = "Unique name of the edge", required = true)
  429 + @RequestParam String edgeName) throws ThingsboardException {
357 430 try {
358 431 TenantId tenantId = getCurrentUser().getTenantId();
359 432 return checkNotNull(edgeService.findEdgeByTenantIdAndName(tenantId, edgeName));
... ... @@ -362,10 +435,16 @@ public class EdgeController extends BaseController {
362 435 }
363 436 }
364 437
  438 + @ApiOperation(value = "Set root rule chain for provided edge (setRootRuleChain)",
  439 + notes = "Change root rule chain of the edge to the new provided rule chain. \n" +
  440 + "This operation will send a notification to update root rule chain on remote edge service.",
  441 + produces = MediaType.APPLICATION_JSON_VALUE)
365 442 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
366 443 @RequestMapping(value = "/edge/{edgeId}/{ruleChainId}/root", method = RequestMethod.POST)
367 444 @ResponseBody
368   - public Edge setRootRuleChain(@PathVariable(EDGE_ID) String strEdgeId,
  445 + public Edge setRootRuleChain(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  446 + @PathVariable(EDGE_ID) String strEdgeId,
  447 + @ApiParam(value = RULE_CHAIN_ID_PARAM_DESCRIPTION, required = true)
369 448 @PathVariable("ruleChainId") String strRuleChainId) throws ThingsboardException {
370 449 checkParameter(EDGE_ID, strEdgeId);
371 450 checkParameter("ruleChainId", strRuleChainId);
... ... @@ -394,16 +473,26 @@ public class EdgeController extends BaseController {
394 473 }
395 474 }
396 475
  476 + @ApiOperation(value = "Get Customer Edges (getCustomerEdges)",
  477 + notes = "Returns a page of edges objects assigned to customer. " +
  478 + PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
397 479 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
398 480 @RequestMapping(value = "/customer/{customerId}/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
399 481 @ResponseBody
400 482 public PageData<Edge> getCustomerEdges(
  483 + @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
401 484 @PathVariable("customerId") String strCustomerId,
  485 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
402 486 @RequestParam int pageSize,
  487 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
403 488 @RequestParam int page,
  489 + @ApiParam(value = EDGE_TYPE_DESCRIPTION)
404 490 @RequestParam(required = false) String type,
  491 + @ApiParam(value = EDGE_TEXT_SEARCH_DESCRIPTION)
405 492 @RequestParam(required = false) String textSearch,
  493 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EDGE_SORT_PROPERTY_ALLOWABLE_VALUES)
406 494 @RequestParam(required = false) String sortProperty,
  495 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
407 496 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
408 497 checkParameter("customerId", strCustomerId);
409 498 try {
... ... @@ -429,16 +518,26 @@ public class EdgeController extends BaseController {
429 518 }
430 519 }
431 520
  521 + @ApiOperation(value = "Get Customer Edge Infos (getCustomerEdgeInfos)",
  522 + notes = "Returns a page of edges info objects assigned to customer. " +
  523 + PAGE_DATA_PARAMETERS + EDGE_INFO_DESCRIPTION, produces = MediaType.APPLICATION_JSON_VALUE)
432 524 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
433 525 @RequestMapping(value = "/customer/{customerId}/edgeInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
434 526 @ResponseBody
435 527 public PageData<EdgeInfo> getCustomerEdgeInfos(
  528 + @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
436 529 @PathVariable("customerId") String strCustomerId,
  530 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
437 531 @RequestParam int pageSize,
  532 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
438 533 @RequestParam int page,
  534 + @ApiParam(value = EDGE_TYPE_DESCRIPTION)
439 535 @RequestParam(required = false) String type,
  536 + @ApiParam(value = EDGE_TEXT_SEARCH_DESCRIPTION)
440 537 @RequestParam(required = false) String textSearch,
  538 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EDGE_SORT_PROPERTY_ALLOWABLE_VALUES)
441 539 @RequestParam(required = false) String sortProperty,
  540 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
442 541 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
443 542 checkParameter("customerId", strCustomerId);
444 543 try {
... ... @@ -464,10 +563,14 @@ public class EdgeController extends BaseController {
464 563 }
465 564 }
466 565
  566 + @ApiOperation(value = "Get Edges By Ids (getEdgesByIds)",
  567 + notes = "Requested edges must be owned by tenant or assigned to customer which user is performing the request.",
  568 + produces = MediaType.APPLICATION_JSON_VALUE)
467 569 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
468 570 @RequestMapping(value = "/edges", params = {"edgeIds"}, method = RequestMethod.GET)
469 571 @ResponseBody
470 572 public List<Edge> getEdgesByIds(
  573 + @ApiParam(value = "A list of edges ids, separated by comma ','", required = true)
471 574 @RequestParam("edgeIds") String[] strEdgeIds) throws ThingsboardException {
472 575 checkArrayParameter("edgeIds", strEdgeIds);
473 576 try {
... ... @@ -496,6 +599,11 @@ public class EdgeController extends BaseController {
496 599 }
497 600 }
498 601
  602 + @ApiOperation(value = "Find related edges (findByQuery)",
  603 + notes = "Returns all edges that are related to the specific entity. " +
  604 + "The entity id, relation type, edge types, depth of the search, and other query parameters defined using complex 'EdgeSearchQuery' object. " +
  605 + "See 'Model' tab of the Parameters for more info.",
  606 + produces = MediaType.APPLICATION_JSON_VALUE)
499 607 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
500 608 @RequestMapping(value = "/edges", method = RequestMethod.POST)
501 609 @ResponseBody
... ... @@ -527,6 +635,9 @@ public class EdgeController extends BaseController {
527 635 }
528 636 }
529 637
  638 + @ApiOperation(value = "Get Edge Types (getEdgeTypes)",
  639 + 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.",
  640 + produces = MediaType.APPLICATION_JSON_VALUE)
530 641 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
531 642 @RequestMapping(value = "/edge/types", method = RequestMethod.GET)
532 643 @ResponseBody
... ... @@ -541,9 +652,13 @@ public class EdgeController extends BaseController {
541 652 }
542 653 }
543 654
  655 + @ApiOperation(value = "Sync edge (syncEdge)",
  656 + notes = "Starts synchronization process between edge and cloud. \n" +
  657 + "All entities that are assigned to particular edge are going to be send to remote edge service.")
544 658 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
545 659 @RequestMapping(value = "/edge/sync/{edgeId}", method = RequestMethod.POST)
546   - public void syncEdge(@PathVariable("edgeId") String strEdgeId) throws ThingsboardException {
  660 + public void syncEdge(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  661 + @PathVariable("edgeId") String strEdgeId) throws ThingsboardException {
547 662 checkParameter("edgeId", strEdgeId);
548 663 try {
549 664 if (isEdgesEnabled()) {
... ... @@ -560,10 +675,13 @@ public class EdgeController extends BaseController {
560 675 }
561 676 }
562 677
  678 + @ApiOperation(value = "Find missing rule chains (findMissingToRelatedRuleChains)",
  679 + 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.")
563 680 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
564 681 @RequestMapping(value = "/edge/missingToRelatedRuleChains/{edgeId}", method = RequestMethod.GET)
565 682 @ResponseBody
566   - public String findMissingToRelatedRuleChains(@PathVariable("edgeId") String strEdgeId) throws ThingsboardException {
  683 + public String findMissingToRelatedRuleChains(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
  684 + @PathVariable("edgeId") String strEdgeId) throws ThingsboardException {
567 685 try {
568 686 EdgeId edgeId = new EdgeId(toUUID(strEdgeId));
569 687 edgeId = checkNotNull(edgeId);
... ... @@ -575,9 +693,12 @@ public class EdgeController extends BaseController {
575 693 }
576 694 }
577 695
  696 + @ApiOperation(value = "Import the bulk of edges (processEdgesBulkImport)",
  697 + notes = "There's an ability to import the bulk of edges using the only .csv file.",
  698 + produces = MediaType.APPLICATION_JSON_VALUE)
578 699 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
579 700 @PostMapping("/edge/bulk_import")
580   - public BulkImportResult<Edge> processEdgeBulkImport(@RequestBody BulkImportRequest request) throws Exception {
  701 + public BulkImportResult<Edge> processEdgesBulkImport(@RequestBody BulkImportRequest request) throws Exception {
581 702 SecurityUser user = getCurrentUser();
582 703 RuleChain edgeTemplateRootRuleChain = ruleChainService.getEdgeTemplateRootRuleChain(user.getTenantId());
583 704 if (edgeTemplateRootRuleChain == null) {
... ...
... ... @@ -15,8 +15,11 @@
15 15 */
16 16 package org.thingsboard.server.controller;
17 17
  18 +import io.swagger.annotations.ApiOperation;
  19 +import io.swagger.annotations.ApiParam;
18 20 import lombok.extern.slf4j.Slf4j;
19 21 import org.springframework.beans.factory.annotation.Autowired;
  22 +import org.springframework.http.MediaType;
20 23 import org.springframework.security.access.prepost.PreAuthorize;
21 24 import org.springframework.web.bind.annotation.PathVariable;
22 25 import org.springframework.web.bind.annotation.RequestMapping;
... ... @@ -45,17 +48,28 @@ public class EdgeEventController extends BaseController {
45 48
46 49 public static final String EDGE_ID = "edgeId";
47 50
  51 + @ApiOperation(value = "Get Edge Events (getEdgeEvents)",
  52 + notes = "Returns a page of edge events for the requested edge. " +
  53 + PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
48 54 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
49 55 @RequestMapping(value = "/edge/{edgeId}/events", method = RequestMethod.GET)
50 56 @ResponseBody
51 57 public PageData<EdgeEvent> getEdgeEvents(
  58 + @ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
52 59 @PathVariable(EDGE_ID) String strEdgeId,
  60 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
53 61 @RequestParam int pageSize,
  62 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
54 63 @RequestParam int page,
  64 + @ApiParam(value = "The case insensitive 'startsWith' filter based on the edge event type name.")
55 65 @RequestParam(required = false) String textSearch,
  66 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EDGE_SORT_PROPERTY_ALLOWABLE_VALUES)
56 67 @RequestParam(required = false) String sortProperty,
  68 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
57 69 @RequestParam(required = false) String sortOrder,
  70 + @ApiParam(value = "Timestamp. Edge events with creation time before it won't be queried")
58 71 @RequestParam(required = false) Long startTime,
  72 + @ApiParam(value = "Timestamp. Edge events with creation time after it won't be queried")
59 73 @RequestParam(required = false) Long endTime) throws ThingsboardException {
60 74 checkParameter(EDGE_ID, strEdgeId);
61 75 try {
... ...
... ... @@ -15,7 +15,6 @@
15 15 */
16 16 package org.thingsboard.server.dao.model.sql;
17 17
18   -import com.datastax.oss.driver.api.core.uuid.Uuids;
19 18 import com.fasterxml.jackson.databind.JsonNode;
20 19 import lombok.Data;
21 20 import lombok.EqualsAndHashCode;
... ... @@ -40,15 +39,14 @@ import javax.persistence.Table;
40 39 import java.util.UUID;
41 40
42 41 import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_ACTION_PROPERTY;
  42 +import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_BODY_PROPERTY;
43 43 import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_COLUMN_FAMILY_NAME;
44 44 import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_EDGE_ID_PROPERTY;
45   -import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_BODY_PROPERTY;
46 45 import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_ENTITY_ID_PROPERTY;
47 46 import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_TENANT_ID_PROPERTY;
48 47 import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_TYPE_PROPERTY;
49 48 import static org.thingsboard.server.dao.model.ModelConstants.EDGE_EVENT_UID_PROPERTY;
50 49 import static org.thingsboard.server.dao.model.ModelConstants.EPOCH_DIFF;
51   -import static org.thingsboard.server.dao.model.ModelConstants.EVENT_UID_PROPERTY;
52 50 import static org.thingsboard.server.dao.model.ModelConstants.TS_COLUMN;
53 51
54 52 @Data
... ...
... ... @@ -31,10 +31,12 @@ public interface EdgeEventRepository extends PagingAndSortingRepository<EdgeEven
31 31 "e.tenantId = :tenantId " +
32 32 "AND e.edgeId = :edgeId " +
33 33 "AND (:startTime IS NULL OR e.createdTime >= :startTime) " +
34   - "AND (:endTime IS NULL OR e.createdTime <= :endTime) "
  34 + "AND (:endTime IS NULL OR e.createdTime <= :endTime) " +
  35 + "AND LOWER(e.edgeEventType) LIKE LOWER(CONCAT(:textSearch, '%'))"
35 36 )
36 37 Page<EdgeEventEntity> findEdgeEventsByTenantIdAndEdgeId(@Param("tenantId") UUID tenantId,
37 38 @Param("edgeId") UUID edgeId,
  39 + @Param("textSearch") String textSearch,
38 40 @Param("startTime") Long startTime,
39 41 @Param("endTime") Long endTime,
40 42 Pageable pageable);
... ... @@ -44,10 +46,12 @@ public interface EdgeEventRepository extends PagingAndSortingRepository<EdgeEven
44 46 "AND e.edgeId = :edgeId " +
45 47 "AND (:startTime IS NULL OR e.createdTime >= :startTime) " +
46 48 "AND (:endTime IS NULL OR e.createdTime <= :endTime) " +
47   - "AND e.edgeEventAction <> 'TIMESERIES_UPDATED'"
  49 + "AND e.edgeEventAction <> 'TIMESERIES_UPDATED' " +
  50 + "AND LOWER(e.edgeEventType) LIKE LOWER(CONCAT(:textSearch, '%'))"
48 51 )
49 52 Page<EdgeEventEntity> findEdgeEventsByTenantIdAndEdgeIdWithoutTimeseriesUpdated(@Param("tenantId") UUID tenantId,
50 53 @Param("edgeId") UUID edgeId,
  54 + @Param("textSearch") String textSearch,
51 55 @Param("startTime") Long startTime,
52 56 @Param("endTime") Long endTime,
53 57 Pageable pageable);
... ...
... ... @@ -39,6 +39,7 @@ import java.sql.Connection;
39 39 import java.sql.PreparedStatement;
40 40 import java.sql.ResultSet;
41 41 import java.sql.SQLException;
  42 +import java.util.Objects;
42 43 import java.util.Optional;
43 44 import java.util.UUID;
44 45 import java.util.concurrent.ConcurrentHashMap;
... ... @@ -107,6 +108,7 @@ public class JpaBaseEdgeEventDao extends JpaAbstractSearchTextDao<EdgeEventEntit
107 108 .findEdgeEventsByTenantIdAndEdgeId(
108 109 tenantId,
109 110 edgeId.getId(),
  111 + Objects.toString(pageLink.getTextSearch(), ""),
110 112 pageLink.getStartTime(),
111 113 pageLink.getEndTime(),
112 114 DaoUtil.toPageable(pageLink)));
... ... @@ -116,6 +118,7 @@ public class JpaBaseEdgeEventDao extends JpaAbstractSearchTextDao<EdgeEventEntit
116 118 .findEdgeEventsByTenantIdAndEdgeIdWithoutTimeseriesUpdated(
117 119 tenantId,
118 120 edgeId.getId(),
  121 + Objects.toString(pageLink.getTextSearch(), ""),
119 122 pageLink.getStartTime(),
120 123 pageLink.getEndTime(),
121 124 DaoUtil.toPageable(pageLink)));
... ...