简柏林 / thingskit · Commits

Commit f47e1c7e3700b30dc6e30e9c205c4ce59f180a9b

Authored by Andrii Shvaika
1 parent 2e187df4

Alarm Swagger Docs

Inline Side-by-side
Showing 3 changed files with 29 additions and 16 deletions
@@ -58,8 +58,8 @@ import java.util.List; @@ -58,8 +58,8 @@ import java.util.List;
58 public class AlarmController extends BaseController { 58 public class AlarmController extends BaseController {
59 59
60 public static final String ALARM_ID = "alarmId"; 60 public static final String ALARM_ID = "alarmId";
61 - 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. " +  
62 - "If the user has the authority of 'Customer User', the server checks that the alarm belongs to the customer. "; 61 + 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. " +
  62 + "If the user has the authority of 'Customer User', the server checks that the originator of alarm belongs to the customer. ";
63 private static final String ALARM_QUERY_SEARCH_STATUS_DESCRIPTION = "A string value representing one of the AlarmSearchStatus enumeration value"; 63 private static final String ALARM_QUERY_SEARCH_STATUS_DESCRIPTION = "A string value representing one of the AlarmSearchStatus enumeration value";
64 private static final String ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES = "ANY, ACTIVE, CLEARED, ACK, UNACK"; 64 private static final String ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES = "ANY, ACTIVE, CLEARED, ACK, UNACK";
65 private static final String ALARM_QUERY_STATUS_DESCRIPTION = "A string value representing one of the AlarmStatus enumeration value"; 65 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 { @@ -104,9 +104,15 @@ public class AlarmController extends BaseController {
104 } 104 }
105 105
106 @ApiOperation(value = "Create or update Alarm (saveAlarm)", 106 @ApiOperation(value = "Create or update Alarm (saveAlarm)",
107 - notes = "Creates or Updates the Alarm. Platform generates random Alarm Id during alarm creation. " +  
108 - "The Alarm Id will be present in the response. Specify the Alarm Id when you would like to update the Alarm. " +  
109 - "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE) 107 + notes = "Creates or Updates the Alarm. " +
  108 + "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). " +
  109 + "The newly created Alarm id will be present in the response. Specify existing Alarm id to update the alarm. " +
  110 + "Referencing non-existing Alarm Id will cause 'Not Found' error. " +
  111 + "\n\nPlatform also deduplicate the alarms based on the entity id of originator and alarm 'type'. " +
  112 + "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. " +
  113 + "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). " +
  114 + "If the user clears the alarm (see 'Clear Alarm(clearAlarm)'), than new alarm with the same type and same device may be created. "
  115 + , produces = MediaType.APPLICATION_JSON_VALUE)
110 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')") 116 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
111 @RequestMapping(value = "/alarm", method = RequestMethod.POST) 117 @RequestMapping(value = "/alarm", method = RequestMethod.POST)
112 @ResponseBody 118 @ResponseBody
@@ -157,7 +163,9 @@ public class AlarmController extends BaseController { @@ -157,7 +163,9 @@ public class AlarmController extends BaseController {
157 } 163 }
158 164
159 @ApiOperation(value = "Acknowledge Alarm (ackAlarm)", 165 @ApiOperation(value = "Acknowledge Alarm (ackAlarm)",
160 - notes = "Acknowledge the Alarm. Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE) 166 + notes = "Acknowledge the Alarm. " +
  167 + "Once acknowledged, the 'ack_ts' field will be set to current timestamp and special rule chain event 'ALARM_ACK' will be generated. " +
  168 + "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
161 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')") 169 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
162 @RequestMapping(value = "/alarm/{alarmId}/ack", method = RequestMethod.POST) 170 @RequestMapping(value = "/alarm/{alarmId}/ack", method = RequestMethod.POST)
163 @ResponseStatus(value = HttpStatus.OK) 171 @ResponseStatus(value = HttpStatus.OK)
@@ -179,7 +187,9 @@ public class AlarmController extends BaseController { @@ -179,7 +187,9 @@ public class AlarmController extends BaseController {
179 } 187 }
180 188
181 @ApiOperation(value = "Clear Alarm (clearAlarm)", 189 @ApiOperation(value = "Clear Alarm (clearAlarm)",
182 - notes = "Clear the Alarm. Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE) 190 + notes = "Clear the Alarm. " +
  191 + "Once cleared, the 'clear_ts' field will be set to current timestamp and special rule chain event 'ALARM_CLEAR' will be generated. " +
  192 + "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
183 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')") 193 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
184 @RequestMapping(value = "/alarm/{alarmId}/clear", method = RequestMethod.POST) 194 @RequestMapping(value = "/alarm/{alarmId}/clear", method = RequestMethod.POST)
185 @ResponseStatus(value = HttpStatus.OK) 195 @ResponseStatus(value = HttpStatus.OK)
@@ -215,9 +225,9 @@ public class AlarmController extends BaseController { @@ -215,9 +225,9 @@ public class AlarmController extends BaseController {
215 @RequestParam(required = false) String searchStatus, 225 @RequestParam(required = false) String searchStatus,
216 @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES) 226 @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES)
217 @RequestParam(required = false) String status, 227 @RequestParam(required = false) String status,
218 - @ApiParam(value = PAGE_SIZE_DESCRIPTION) 228 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
219 @RequestParam int pageSize, 229 @RequestParam int pageSize,
220 - @ApiParam(value = PAGE_NUMBER_DESCRIPTION) 230 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
221 @RequestParam int page, 231 @RequestParam int page,
222 @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION) 232 @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION)
223 @RequestParam(required = false) String textSearch, 233 @RequestParam(required = false) String textSearch,
@@ -264,9 +274,9 @@ public class AlarmController extends BaseController { @@ -264,9 +274,9 @@ public class AlarmController extends BaseController {
264 @RequestParam(required = false) String searchStatus, 274 @RequestParam(required = false) String searchStatus,
265 @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES) 275 @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES)
266 @RequestParam(required = false) String status, 276 @RequestParam(required = false) String status,
267 - @ApiParam(value = PAGE_SIZE_DESCRIPTION) 277 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
268 @RequestParam int pageSize, 278 @RequestParam int pageSize,
269 - @ApiParam(value = PAGE_NUMBER_DESCRIPTION) 279 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
270 @RequestParam int page, 280 @RequestParam int page,
271 @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION) 281 @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION)
272 @RequestParam(required = false) String textSearch, 282 @RequestParam(required = false) String textSearch,
@@ -301,14 +311,16 @@ public class AlarmController extends BaseController { @@ -301,14 +311,16 @@ public class AlarmController extends BaseController {
301 } 311 }
302 312
303 @ApiOperation(value = "Get Highest Alarm Severity (getHighestAlarmSeverity)", 313 @ApiOperation(value = "Get Highest Alarm Severity (getHighestAlarmSeverity)",
304 - notes = "Returns highest AlarmSeverity object for the selected entity.", produces = MediaType.APPLICATION_JSON_VALUE) 314 + 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). " +
  315 + "Specifying both parameters 'searchStatus' and 'status' at the same time will cause an error."
  316 + , produces = MediaType.APPLICATION_JSON_VALUE)
305 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')") 317 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
306 @RequestMapping(value = "/alarm/highestSeverity/{entityType}/{entityId}", method = RequestMethod.GET) 318 @RequestMapping(value = "/alarm/highestSeverity/{entityType}/{entityId}", method = RequestMethod.GET)
307 @ResponseBody 319 @ResponseBody
308 public AlarmSeverity getHighestAlarmSeverity( 320 public AlarmSeverity getHighestAlarmSeverity(
309 - @ApiParam(value = ENTITY_TYPE_DESCRIPTION) 321 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true)
310 @PathVariable("entityType") String strEntityType, 322 @PathVariable("entityType") String strEntityType,
311 - @ApiParam(value = ENTITY_ID_DESCRIPTION) 323 + @ApiParam(value = ENTITY_ID_DESCRIPTION, required = true)
312 @PathVariable("entityId") String strEntityId, 324 @PathVariable("entityId") String strEntityId,
313 @ApiParam(value = ALARM_QUERY_SEARCH_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES) 325 @ApiParam(value = ALARM_QUERY_SEARCH_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES)
314 @RequestParam(required = false) String searchStatus, 326 @RequestParam(required = false) String searchStatus,
@@ -189,7 +189,7 @@ public abstract class BaseController { @@ -189,7 +189,7 @@ public abstract class BaseController {
189 protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC"; 189 protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
190 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. "; 190 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. ";
191 protected final String ASSET_INFO_DESCRIPTION = "Asset Info is an extension of the default Asset object that contains information about the assigned customer name. "; 191 protected final String ASSET_INFO_DESCRIPTION = "Asset Info is an extension of the default Asset object that contains information about the assigned customer name. ";
192 - protected final String ALARM_INFO_DESCRIPTION = "Alarm Info is an extension of the default Alarm object that contains information about alarm originator name."; 192 + protected final String ALARM_INFO_DESCRIPTION = "Alarm Info is an extension of the default Alarm object that also contains name of the alarm originator.";
193 193
194 194
195 protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name."; 195 protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name.";
@@ -141,7 +141,8 @@ public class DeviceController extends BaseController { @@ -141,7 +141,8 @@ public class DeviceController extends BaseController {
141 "Device credentials are also generated if not provided in the 'accessToken' request parameter. " + 141 "Device credentials are also generated if not provided in the 'accessToken' request parameter. " +
142 "The newly created device id will be present in the response. " + 142 "The newly created device id will be present in the response. " +
143 "Specify existing Device id to update the device. " + 143 "Specify existing Device id to update the device. " +
144 - "Referencing non-existing device Id will cause 'Not Found' error.") 144 + "Referencing non-existing device Id will cause 'Not Found' error." +
  145 + "\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.")
145 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')") 146 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
146 @RequestMapping(value = "/device", method = RequestMethod.POST) 147 @RequestMapping(value = "/device", method = RequestMethod.POST)
147 @ResponseBody 148 @ResponseBody