简柏林 / thingskit · Commits

Commit 2e6b839a41624a3057f2229d586a55ac183c391f

Authored by ShvaykaD
1 parent fe70b091

added swagger docs for audit log controller

Inline Side-by-side
Showing 5 changed files with 76 additions and 45 deletions
... ... @@ -65,8 +65,8 @@ public class AlarmController extends BaseController {
65 65 private static final String ALARM_QUERY_STATUS_DESCRIPTION = "A string value representing one of the AlarmStatus enumeration value";
66 66 private static final String ALARM_QUERY_STATUS_ALLOWABLE_VALUES = "ACTIVE_UNACK, ACTIVE_ACK, CLEARED_UNACK, CLEARED_ACK";
67 67 private static final String ALARM_QUERY_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on of next alarm fields: type, severity or status";
68   - private static final String ALARM_QUERY_START_TIME_DESCRIPTION = "The start timestamp(milliseconds) of the search time range over the alarm object field: 'createdTime'.";
69   - private static final String ALARM_QUERY_END_TIME_DESCRIPTION = "The end timestamp(milliseconds) of the search time range over the alarm object field: 'createdTime'.";
  68 + private static final String ALARM_QUERY_START_TIME_DESCRIPTION = "The start timestamp in milliseconds of the search time range over the Alarm class field: 'createdTime'.";
  69 + private static final String ALARM_QUERY_END_TIME_DESCRIPTION = "The end timestamp in milliseconds of the search time range over the Alarm class field: 'createdTime'.";
70 70 private static final String ALARM_QUERY_FETCH_ORIGINATOR_DESCRIPTION = "A boolean value to specify if the alarm originator name will be " +
71 71 "filled in the AlarmInfo object field: 'originatorName' or will returns as null.";
72 72
... ...
... ... @@ -47,13 +47,20 @@ import java.util.stream.Collectors;
47 47 @RequestMapping("/api")
48 48 public class AuditLogController extends BaseController {
49 49
50   - protected final String AUDIT_LOG_ACTION_TYPES_DESCRIPTION = "A String value representing action types parameter. The value is not required, but it can be any value of ActionType class. " +
51   - "For example, 'ADDED,DELETED,UPDATED,LOGIN,LOGOUT'.";
52   - protected final String SORT_AUDIT_LOG_PROPERTY_DESCRIPTION = "Property of logs to sort by";
53   - protected final String SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES = "createdTime, entityName, entityType, user, type, status";
  50 + private static final String AUDIT_LOG_QUERY_START_TIME_DESCRIPTION = "The start timestamp in milliseconds of the search time range over the AuditLog class field: 'createdTime'.";
  51 + private static final String AUDIT_LOG_QUERY_END_TIME_DESCRIPTION = "The end timestamp in milliseconds of the search time range over the AuditLog class field: 'createdTime'.";
  52 + private static final String AUDIT_LOG_QUERY_ACTION_TYPES_DESCRIPTION = "A String value representing comma-separated list of action types. " +
  53 + "This parameter is optional, but it can be used to filter results to fetch only audit logs of specific action types. " +
  54 + "For example, 'LOGIN', 'LOGOUT'. See the 'Model' tab of the Response Class for more details.";
  55 + private static final String AUDIT_LOG_SORT_PROPERTY_DESCRIPTION = "Property of audit log to sort by. " +
  56 + "See the 'Model' tab of the Response Class for more details. " +
  57 + "Note: entityType sort property is not defined in the AuditLog class, however, it can be used to sort audit logs by types of entities that were logged.";
  58 +
54 59
55 60 @ApiOperation(value = "Get audit logs by customer id (getAuditLogsByCustomerId)",
56   - notes = "Returns a page of audit logs by selected customer. " + PAGE_DATA_PARAMETERS,
  61 + notes = "Returns a page of audit logs related to the targeted customer entities(devices, assets, etc.), " +
  62 + "and users actions(login, logout, etc.) that belong to this customer. " +
  63 + PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
57 64 produces = MediaType.APPLICATION_JSON_VALUE)
58 65 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
59 66 @RequestMapping(value = "/audit/logs/customer/{customerId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -65,17 +72,17 @@ public class AuditLogController extends BaseController {
65 72 @RequestParam int pageSize,
66 73 @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
67 74 @RequestParam int page,
68   - @ApiParam(value = "The case insensitive 'startsWith' filter based on the customer name.")
  75 + @ApiParam(value = AUDIT_LOG_TEXT_SEARCH_DESCRIPTION)
69 76 @RequestParam(required = false) String textSearch,
70   - @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
  77 + @ApiParam(value = AUDIT_LOG_SORT_PROPERTY_DESCRIPTION, allowableValues = AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES)
71 78 @RequestParam(required = false) String sortProperty,
72 79 @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
73 80 @RequestParam(required = false) String sortOrder,
74   - @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
  81 + @ApiParam(value = AUDIT_LOG_QUERY_START_TIME_DESCRIPTION)
75 82 @RequestParam(required = false) Long startTime,
76   - @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
  83 + @ApiParam(value = AUDIT_LOG_QUERY_END_TIME_DESCRIPTION)
77 84 @RequestParam(required = false) Long endTime,
78   - @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
  85 + @ApiParam(value = AUDIT_LOG_QUERY_ACTION_TYPES_DESCRIPTION)
79 86 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
80 87 try {
81 88 checkParameter("CustomerId", strCustomerId);
... ... @@ -89,7 +96,9 @@ public class AuditLogController extends BaseController {
89 96 }
90 97
91 98 @ApiOperation(value = "Get audit logs by user id (getAuditLogsByUserId)",
92   - notes = "Returns a page of audit logs by selected user. " + PAGE_DATA_PARAMETERS,
  99 + notes = "Returns a page of audit logs related to the actions of targeted user. " +
  100 + "For example, RPC call to a particular device, or alarm acknowledgment for a specific device, etc. " +
  101 + PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
93 102 produces = MediaType.APPLICATION_JSON_VALUE)
94 103 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
95 104 @RequestMapping(value = "/audit/logs/user/{userId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -101,17 +110,17 @@ public class AuditLogController extends BaseController {
101 110 @RequestParam int pageSize,
102 111 @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
103 112 @RequestParam int page,
104   - @ApiParam(value = "The case insensitive 'startsWith' filter based on the user name.")
  113 + @ApiParam(value = AUDIT_LOG_TEXT_SEARCH_DESCRIPTION)
105 114 @RequestParam(required = false) String textSearch,
106   - @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
  115 + @ApiParam(value = AUDIT_LOG_SORT_PROPERTY_DESCRIPTION, allowableValues = AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES)
107 116 @RequestParam(required = false) String sortProperty,
108 117 @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
109 118 @RequestParam(required = false) String sortOrder,
110   - @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
  119 + @ApiParam(value = AUDIT_LOG_QUERY_START_TIME_DESCRIPTION)
111 120 @RequestParam(required = false) Long startTime,
112   - @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
  121 + @ApiParam(value = AUDIT_LOG_QUERY_END_TIME_DESCRIPTION)
113 122 @RequestParam(required = false) Long endTime,
114   - @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
  123 + @ApiParam(value = AUDIT_LOG_QUERY_ACTION_TYPES_DESCRIPTION)
115 124 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
116 125 try {
117 126 checkParameter("UserId", strUserId);
... ... @@ -125,31 +134,34 @@ public class AuditLogController extends BaseController {
125 134 }
126 135
127 136 @ApiOperation(value = "Get audit logs by entity id (getAuditLogsByEntityId)",
128   - notes = "Returns a page of audit logs by selected entity. " + PAGE_DATA_PARAMETERS,
  137 + notes = "Returns a page of audit logs related to the actions on the targeted entity. " +
  138 + "Basically, this API call is used to get the full lifecycle of some specific entity. " +
  139 + "For example to see when a device was created, updated, assigned to some customer, or even deleted from the system. " +
  140 + PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
129 141 produces = MediaType.APPLICATION_JSON_VALUE)
130 142 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
131 143 @RequestMapping(value = "/audit/logs/entity/{entityType}/{entityId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
132 144 @ResponseBody
133 145 public PageData<AuditLog> getAuditLogsByEntityId(
134   - @ApiParam(value = ENTITY_TYPE_DESCRIPTION)
  146 + @ApiParam(value = ENTITY_TYPE_PARAM_DESCRIPTION)
135 147 @PathVariable("entityType") String strEntityType,
136   - @ApiParam(value = ENTITY_ID_DESCRIPTION)
  148 + @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION)
137 149 @PathVariable("entityId") String strEntityId,
138 150 @ApiParam(value = PAGE_SIZE_DESCRIPTION)
139 151 @RequestParam int pageSize,
140 152 @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
141 153 @RequestParam int page,
142   - @ApiParam(value = "The case insensitive 'startsWith' filter based on the entity name.")
  154 + @ApiParam(value = AUDIT_LOG_TEXT_SEARCH_DESCRIPTION)
143 155 @RequestParam(required = false) String textSearch,
144   - @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
  156 + @ApiParam(value = AUDIT_LOG_SORT_PROPERTY_DESCRIPTION, allowableValues = AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES)
145 157 @RequestParam(required = false) String sortProperty,
146 158 @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
147 159 @RequestParam(required = false) String sortOrder,
148   - @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
  160 + @ApiParam(value = AUDIT_LOG_QUERY_START_TIME_DESCRIPTION)
149 161 @RequestParam(required = false) Long startTime,
150   - @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
  162 + @ApiParam(value = AUDIT_LOG_QUERY_END_TIME_DESCRIPTION)
151 163 @RequestParam(required = false) Long endTime,
152   - @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
  164 + @ApiParam(value = AUDIT_LOG_QUERY_ACTION_TYPES_DESCRIPTION)
153 165 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
154 166 try {
155 167 checkParameter("EntityId", strEntityId);
... ... @@ -164,7 +176,9 @@ public class AuditLogController extends BaseController {
164 176 }
165 177
166 178 @ApiOperation(value = "Get all audit logs (getAuditLogs)",
167   - notes = "Returns a page of all audit logs. " + PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
  179 + notes = "Returns a page of audit logs related to all entities in the scope of the current user's Tenant. " +
  180 + PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
  181 + produces = MediaType.APPLICATION_JSON_VALUE)
168 182 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
169 183 @RequestMapping(value = "/audit/logs", params = {"pageSize", "page"}, method = RequestMethod.GET)
170 184 @ResponseBody
... ... @@ -173,17 +187,17 @@ public class AuditLogController extends BaseController {
173 187 @RequestParam int pageSize,
174 188 @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
175 189 @RequestParam int page,
176   - @ApiParam(value = "The case insensitive 'startsWith' filter based on any name like 'Device', 'Asset', 'Customer' etc.")
  190 + @ApiParam(value = AUDIT_LOG_TEXT_SEARCH_DESCRIPTION)
177 191 @RequestParam(required = false) String textSearch,
178   - @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
  192 + @ApiParam(value = AUDIT_LOG_SORT_PROPERTY_DESCRIPTION, allowableValues = AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES)
179 193 @RequestParam(required = false) String sortProperty,
180 194 @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
181 195 @RequestParam(required = false) String sortOrder,
182   - @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
  196 + @ApiParam(value = AUDIT_LOG_QUERY_START_TIME_DESCRIPTION)
183 197 @RequestParam(required = false) Long startTime,
184   - @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
  198 + @ApiParam(value = AUDIT_LOG_QUERY_END_TIME_DESCRIPTION)
185 199 @RequestParam(required = false) Long endTime,
186   - @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
  200 + @ApiParam(value = AUDIT_LOG_QUERY_ACTION_TYPES_DESCRIPTION)
187 201 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
188 202 try {
189 203 TenantId tenantId = getCurrentUser().getTenantId();
... ...
... ... @@ -186,6 +186,7 @@ public abstract class BaseController {
186 186 protected final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device name.";
187 187 protected final String CUSTOMER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the customer title.";
188 188 protected final String EVENT_TEXT_SEARCH_DESCRIPTION = "The value is not used in searching.";
  189 + protected final String AUDIT_LOG_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on one of the next properties: entityType, entityName, userName, actionType, actionStatus.";
189 190 protected final String SORT_PROPERTY_DESCRIPTION = "Property of entity to sort by";
190 191 protected final String DASHBOARD_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title";
191 192 protected final String CUSTOMER_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, email, country, city";
... ... @@ -193,6 +194,7 @@ public abstract class BaseController {
193 194 protected final String ASSET_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
194 195 protected final String ALARM_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, startTs, endTs, type, ackTs, clearTs, severity, status";
195 196 protected final String EVENT_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, id";
  197 + protected final String AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, entityType, entityName, userName, actionType, actionStatus";
196 198 protected final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESC (DESCENDING)";
197 199 protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
198 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. ";
... ... @@ -205,8 +207,10 @@ public abstract class BaseController {
205 207
206 208 protected final String EVENT_START_TIME_DESCRIPTION = "Timestamp. Events with creation time before it won't be queried.";
207 209 protected final String EVENT_END_TIME_DESCRIPTION = "Timestamp. Events with creation time after it won't be queried.";
208   - protected static final String RELATION_TYPE_PARAM_DESCRIPTION = "A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value.";
209   - protected static final String RELATION_TYPE_GROUP_PARAM_DESCRIPTION = "A string value representing relation type group. For example, 'COMMON'";
  210 + protected final String RELATION_TYPE_PARAM_DESCRIPTION = "A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value.";
  211 + protected final String RELATION_TYPE_GROUP_PARAM_DESCRIPTION = "A string value representing relation type group. For example, 'COMMON'";
  212 +
  213 + protected final String ADMINISTRATOR_AUTHORITY_ONLY = "Available for users with 'Tenant Administrator' authority only.";
210 214
211 215 public static final String INCORRECT_TENANT_ID = "Incorrect tenantId ";
212 216 protected static final String DEFAULT_DASHBOARD = "defaultDashboardId";
... ...
... ... @@ -212,7 +212,7 @@ public class CustomerController extends BaseController {
212 212 }
213 213
214 214 @ApiOperation(value = "Get Tenant Customer by Customer title (getTenantCustomer)",
215   - notes = "Get the Customer using Customer Title. Available for users with 'Tenant Administrator' authority only.")
  215 + notes = "Get the Customer using Customer Title. " + ADMINISTRATOR_AUTHORITY_ONLY)
216 216 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
217 217 @RequestMapping(value = "/tenant/customers", params = {"customerTitle"}, method = RequestMethod.GET)
218 218 @ResponseBody
... ...
... ... @@ -28,25 +28,25 @@ import org.thingsboard.server.common.data.id.*;
28 28 @Data
29 29 public class AuditLog extends BaseData<AuditLogId> {
30 30
31   - @ApiModelProperty(position = 3, value = "JSON object with Tenant Id.", readOnly = true)
  31 + @ApiModelProperty(position = 3, value = "JSON object with Tenant Id", readOnly = true)
32 32 private TenantId tenantId;
33   - @ApiModelProperty(position = 2, value = "JSON object with Customer Id.", readOnly = true)
  33 + @ApiModelProperty(position = 4, value = "JSON object with Customer Id", readOnly = true)
34 34 private CustomerId customerId;
35   - @ApiModelProperty(position = 3, value = "JSON object with Entity id.", readOnly = true)
  35 + @ApiModelProperty(position = 5, value = "JSON object with Entity id", readOnly = true)
36 36 private EntityId entityId;
37   - @ApiModelProperty(position = 4, value = "Entity Name", example = "Thermometer", readOnly = true)
  37 + @ApiModelProperty(position = 6, value = "Name of the logged entity", example = "Thermometer", readOnly = true)
38 38 private String entityName;
39   - @ApiModelProperty(position = 5, value = "JSON object with User id.", readOnly = true)
  39 + @ApiModelProperty(position = 7, value = "JSON object with User id.", readOnly = true)
40 40 private UserId userId;
41   - @ApiModelProperty(position = 6, value = "Unique User Name in scope of Administrator.", example = "Tenant", readOnly = true)
  41 + @ApiModelProperty(position = 8, value = "Unique user name(email) of the user that performed some action on logged entity", example = "tenant@thingsboard.org", readOnly = true)
42 42 private String userName;
43   - @ApiModelProperty(position = 7, value = "String represented Action type.", readOnly = true)
  43 + @ApiModelProperty(position = 9, value = "String represented Action type", example = "ADDED", readOnly = true)
44 44 private ActionType actionType;
45   - @ApiModelProperty(position = 8, value = "JsonNode represented action data.", readOnly = true)
  45 + @ApiModelProperty(position = 10, value = "JsonNode represented action data", readOnly = true)
46 46 private JsonNode actionData;
47   - @ApiModelProperty(position = 9, value = "string", example = "SUCCESS", allowableValues = "SUCCESS,FAILURE", readOnly = true)
  47 + @ApiModelProperty(position = 11, value = "String represented Action status", example = "SUCCESS", allowableValues = "SUCCESS,FAILURE", readOnly = true)
48 48 private ActionStatus actionStatus;
49   - @ApiModelProperty(position = 10, value = "Action failure details info", readOnly = true)
  49 + @ApiModelProperty(position = 12, value = "Failure action details info. An empty string in case of action status type 'SUCCESS', otherwise includes stack trace of the caused exception.", readOnly = true)
50 50 private String actionFailureDetails;
51 51
52 52 public AuditLog() {
... ... @@ -70,4 +70,17 @@ public class AuditLog extends BaseData<AuditLogId> {
70 70 this.actionStatus = auditLog.getActionStatus();
71 71 this.actionFailureDetails = auditLog.getActionFailureDetails();
72 72 }
  73 +
  74 + @ApiModelProperty(position = 2, value = "Timestamp of the auditLog creation, in milliseconds", example = "1609459200000", readOnly = true)
  75 + @Override
  76 + public long getCreatedTime() {
  77 + return super.getCreatedTime();
  78 + }
  79 +
  80 + @ApiModelProperty(position = 1, value = "JSON object with the auditLog Id")
  81 + @Override
  82 + public AuditLogId getId() {
  83 + return super.getId();
  84 + }
  85 +
73 86 }
... ...