Alarm Swagger Docs

application/src/main/java/org/thingsboard/server/controller/AlarmController.java

@@ -58,8 +58,8 @@ import java.util.List;
 public class AlarmController extends BaseController {
 
     public static final String ALARM_ID = "alarmId";
-    private static final String ALARM_SECURITY_CHECK = "If the user has the authority of 'Tenant Administrator', the server checks that the alarm is owned by the same tenant. " +
-            "If the user has the authority of 'Customer User', the server checks that the alarm belongs to the customer. ";
+    private static final String ALARM_SECURITY_CHECK = "If the user has the authority of 'Tenant Administrator', the server checks that the originator of alarm is owned by the same tenant. " +
+            "If the user has the authority of 'Customer User', the server checks that the originator of alarm belongs to the customer. ";
     private static final String ALARM_QUERY_SEARCH_STATUS_DESCRIPTION = "A string value representing one of the AlarmSearchStatus enumeration value";
     private static final String ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES = "ANY, ACTIVE, CLEARED, ACK, UNACK";
     private static final String ALARM_QUERY_STATUS_DESCRIPTION = "A string value representing one of the AlarmStatus enumeration value";
@@ -104,9 +104,15 @@ public class AlarmController extends BaseController {
     }
 
     @ApiOperation(value = "Create or update Alarm (saveAlarm)",
-            notes = "Creates or Updates the Alarm. Platform generates random Alarm Id during alarm creation. " +
-                    "The Alarm Id will be present in the response. Specify the Alarm Id when you would like to update the Alarm. " +
-                    "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
+            notes = "Creates or Updates the Alarm. " +
+                    "When creating alarm, platform generates Alarm Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
+                    "The newly created Alarm id will be present in the response. Specify existing Alarm id to update the alarm. " +
+                    "Referencing non-existing Alarm Id will cause 'Not Found' error. " +
+                    "\n\nPlatform also deduplicate the alarms based on the entity id of originator and alarm 'type'. " +
+                    "For example, if the user or system component create the alarm with the type 'HighTemperature' for device 'Device A' the new active alarm is created. " +
+                    "If the user tries to create 'HighTemperature' alarm for the same device again, the previous alarm will be updated (the 'end_ts' will be set to current timestamp). " +
+                    "If the user clears the alarm (see 'Clear Alarm(clearAlarm)'), than new alarm with the same type and same device may be created. "
+            , produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/alarm", method = RequestMethod.POST)
     @ResponseBody
@@ -157,7 +163,9 @@ public class AlarmController extends BaseController {
     }
 
     @ApiOperation(value = "Acknowledge Alarm (ackAlarm)",
-            notes = "Acknowledge the Alarm. Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
+            notes = "Acknowledge the Alarm. " +
+                    "Once acknowledged, the 'ack_ts' field will be set to current timestamp and special rule chain event 'ALARM_ACK' will be generated. " +
+                    "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/alarm/{alarmId}/ack", method = RequestMethod.POST)
     @ResponseStatus(value = HttpStatus.OK)
@@ -179,7 +187,9 @@ public class AlarmController extends BaseController {
     }
 
     @ApiOperation(value = "Clear Alarm (clearAlarm)",
-            notes = "Clear the Alarm. Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
+            notes = "Clear the Alarm. " +
+                    "Once cleared, the 'clear_ts' field will be set to current timestamp and special rule chain event 'ALARM_CLEAR' will be generated. " +
+                    "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/alarm/{alarmId}/clear", method = RequestMethod.POST)
     @ResponseStatus(value = HttpStatus.OK)
@@ -215,9 +225,9 @@ public class AlarmController extends BaseController {
             @RequestParam(required = false) String searchStatus,
             @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES)
             @RequestParam(required = false) String status,
-            @ApiParam(value = PAGE_SIZE_DESCRIPTION)
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
             @RequestParam int pageSize,
-            @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
             @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
@@ -264,9 +274,9 @@ public class AlarmController extends BaseController {
             @RequestParam(required = false) String searchStatus,
             @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES)
             @RequestParam(required = false) String status,
-            @ApiParam(value = PAGE_SIZE_DESCRIPTION)
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
             @RequestParam int pageSize,
-            @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
             @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
@@ -301,14 +311,16 @@ public class AlarmController extends BaseController {
     }
 
     @ApiOperation(value = "Get Highest Alarm Severity (getHighestAlarmSeverity)",
-            notes = "Returns highest AlarmSeverity object for the selected entity.", produces = MediaType.APPLICATION_JSON_VALUE)
+            notes = "Search the alarms by originator ('entityType' and entityId') and optional 'status' or 'searchStatus' filters and returns the highest AlarmSeverity(CRITICAL, MAJOR, MINOR, WARNING or INDETERMINATE). " +
+                    "Specifying both parameters 'searchStatus' and 'status' at the same time will cause an error."
+            , produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/alarm/highestSeverity/{entityType}/{entityId}", method = RequestMethod.GET)
     @ResponseBody
     public AlarmSeverity getHighestAlarmSeverity(
-            @ApiParam(value = ENTITY_TYPE_DESCRIPTION)
+            @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true)
             @PathVariable("entityType") String strEntityType,
-            @ApiParam(value = ENTITY_ID_DESCRIPTION)
+            @ApiParam(value = ENTITY_ID_DESCRIPTION, required = true)
             @PathVariable("entityId") String strEntityId,
             @ApiParam(value = ALARM_QUERY_SEARCH_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES)
             @RequestParam(required = false) String searchStatus,

application/src/main/java/org/thingsboard/server/controller/BaseController.java

@@ -189,7 +189,7 @@ public abstract class BaseController {
     protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
     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. ";
     protected final String ASSET_INFO_DESCRIPTION = "Asset Info is an extension of the default Asset object that contains information about the assigned customer name. ";
-    protected final String ALARM_INFO_DESCRIPTION = "Alarm Info is an extension of the default Alarm object that contains information about alarm originator name.";
+    protected final String ALARM_INFO_DESCRIPTION = "Alarm Info is an extension of the default Alarm object that also contains name of the alarm originator.";
 
 
     protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name.";

application/src/main/java/org/thingsboard/server/controller/DeviceController.java

@@ -141,7 +141,8 @@ public class DeviceController extends BaseController {
             "Device credentials are also generated if not provided in the 'accessToken' request parameter. " +
             "The newly created device id will be present in the response. " +
             "Specify existing Device id to update the device. " +
-            "Referencing non-existing device Id will cause 'Not Found' error.")
+            "Referencing non-existing device Id will cause 'Not Found' error." +
+            "\n\nDevice name is unique in the scope of tenant. Use unique identifiers like MAC or IMEI for the device names and non-unique 'label' field for user-friendly visualization purposes.")
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/device", method = RequestMethod.POST)
     @ResponseBody