简柏林 / 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 58 public class AlarmController extends BaseController {
59 59
60 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 63 private static final String ALARM_QUERY_SEARCH_STATUS_DESCRIPTION = "A string value representing one of the AlarmSearchStatus enumeration value";
64 64 private static final String ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES = "ANY, ACTIVE, CLEARED, ACK, UNACK";
65 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 104 }
105 105
106 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 116 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
111 117 @RequestMapping(value = "/alarm", method = RequestMethod.POST)
112 118 @ResponseBody
... ... @@ -157,7 +163,9 @@ public class AlarmController extends BaseController {
157 163 }
158 164
159 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 169 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
162 170 @RequestMapping(value = "/alarm/{alarmId}/ack", method = RequestMethod.POST)
163 171 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -179,7 +187,9 @@ public class AlarmController extends BaseController {
179 187 }
180 188
181 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 193 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
184 194 @RequestMapping(value = "/alarm/{alarmId}/clear", method = RequestMethod.POST)
185 195 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -215,9 +225,9 @@ public class AlarmController extends BaseController {
215 225 @RequestParam(required = false) String searchStatus,
216 226 @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES)
217 227 @RequestParam(required = false) String status,
218   - @ApiParam(value = PAGE_SIZE_DESCRIPTION)
  228 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
219 229 @RequestParam int pageSize,
220   - @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
  230 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
221 231 @RequestParam int page,
222 232 @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION)
223 233 @RequestParam(required = false) String textSearch,
... ... @@ -264,9 +274,9 @@ public class AlarmController extends BaseController {
264 274 @RequestParam(required = false) String searchStatus,
265 275 @ApiParam(value = ALARM_QUERY_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_STATUS_ALLOWABLE_VALUES)
266 276 @RequestParam(required = false) String status,
267   - @ApiParam(value = PAGE_SIZE_DESCRIPTION)
  277 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
268 278 @RequestParam int pageSize,
269   - @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
  279 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
270 280 @RequestParam int page,
271 281 @ApiParam(value = ALARM_QUERY_TEXT_SEARCH_DESCRIPTION)
272 282 @RequestParam(required = false) String textSearch,
... ... @@ -301,14 +311,16 @@ public class AlarmController extends BaseController {
301 311 }
302 312
303 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 317 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
306 318 @RequestMapping(value = "/alarm/highestSeverity/{entityType}/{entityId}", method = RequestMethod.GET)
307 319 @ResponseBody
308 320 public AlarmSeverity getHighestAlarmSeverity(
309   - @ApiParam(value = ENTITY_TYPE_DESCRIPTION)
  321 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true)
310 322 @PathVariable("entityType") String strEntityType,
311   - @ApiParam(value = ENTITY_ID_DESCRIPTION)
  323 + @ApiParam(value = ENTITY_ID_DESCRIPTION, required = true)
312 324 @PathVariable("entityId") String strEntityId,
313 325 @ApiParam(value = ALARM_QUERY_SEARCH_STATUS_DESCRIPTION, allowableValues = ALARM_QUERY_SEARCH_STATUS_ALLOWABLE_VALUES)
314 326 @RequestParam(required = false) String searchStatus,
... ...
... ... @@ -189,7 +189,7 @@ public abstract class BaseController {
189 189 protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
190 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 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 195 protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name.";
... ...
... ... @@ -141,7 +141,8 @@ public class DeviceController extends BaseController {
141 141 "Device credentials are also generated if not provided in the 'accessToken' request parameter. " +
142 142 "The newly created device id will be present in the response. " +
143 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 146 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
146 147 @RequestMapping(value = "/device", method = RequestMethod.POST)
147 148 @ResponseBody
... ...