简柏林 / thingskit · Commits

Commit a126b888da64ec8d9fc5144c39509b00f9702398

Authored by Mariia Synelnyk
Committed by GitHub
1 parent e6e05c9b

add docs for audit-log controller (#12) 

* added swagger docs for audit logs controller

* add api mpdel to AuditLog class

* added produces to @ApiOperation in AuditLogController
Inline Side-by-side
Showing 3 changed files with 71 additions and 1 deletions
... ... @@ -15,7 +15,10 @@
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 org.apache.commons.lang3.StringUtils;
  21 +import org.springframework.http.MediaType;
19 22 import org.springframework.security.access.prepost.PreAuthorize;
20 23 import org.springframework.web.bind.annotation.PathVariable;
21 24 import org.springframework.web.bind.annotation.RequestMapping;
... ... @@ -44,18 +47,35 @@ import java.util.stream.Collectors;
44 47 @RequestMapping("/api")
45 48 public class AuditLogController extends BaseController {
46 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";
  54 +
  55 + @ApiOperation(value = "Get audit logs by customer id (getAuditLogsByCustomerId)",
  56 + notes = "Returns a page of audit logs by selected customer. " + PAGE_DATA_PARAMETERS,
  57 + produces = MediaType.APPLICATION_JSON_VALUE)
47 58 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
48 59 @RequestMapping(value = "/audit/logs/customer/{customerId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
49 60 @ResponseBody
50 61 public PageData<AuditLog> getAuditLogsByCustomerId(
  62 + @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
51 63 @PathVariable("customerId") String strCustomerId,
  64 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
52 65 @RequestParam int pageSize,
  66 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
53 67 @RequestParam int page,
  68 + @ApiParam(value = "The case insensitive 'startsWith' filter based on the customer name.")
54 69 @RequestParam(required = false) String textSearch,
  70 + @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
55 71 @RequestParam(required = false) String sortProperty,
  72 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
56 73 @RequestParam(required = false) String sortOrder,
  74 + @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
57 75 @RequestParam(required = false) Long startTime,
  76 + @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
58 77 @RequestParam(required = false) Long endTime,
  78 + @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
59 79 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
60 80 try {
61 81 checkParameter("CustomerId", strCustomerId);
... ... @@ -68,18 +88,30 @@ public class AuditLogController extends BaseController {
68 88 }
69 89 }
70 90
  91 + @ApiOperation(value = "Get audit logs by user id (getAuditLogsByUserId)",
  92 + notes = "Returns a page of audit logs by selected user. " + PAGE_DATA_PARAMETERS,
  93 + produces = MediaType.APPLICATION_JSON_VALUE)
71 94 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
72 95 @RequestMapping(value = "/audit/logs/user/{userId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
73 96 @ResponseBody
74 97 public PageData<AuditLog> getAuditLogsByUserId(
  98 + @ApiParam(value = USER_ID_PARAM_DESCRIPTION)
75 99 @PathVariable("userId") String strUserId,
  100 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
76 101 @RequestParam int pageSize,
  102 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
77 103 @RequestParam int page,
  104 + @ApiParam(value = "The case insensitive 'startsWith' filter based on the user name.")
78 105 @RequestParam(required = false) String textSearch,
  106 + @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
79 107 @RequestParam(required = false) String sortProperty,
  108 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
80 109 @RequestParam(required = false) String sortOrder,
  110 + @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
81 111 @RequestParam(required = false) Long startTime,
  112 + @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
82 113 @RequestParam(required = false) Long endTime,
  114 + @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
83 115 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
84 116 try {
85 117 checkParameter("UserId", strUserId);
... ... @@ -92,19 +124,32 @@ public class AuditLogController extends BaseController {
92 124 }
93 125 }
94 126
  127 + @ApiOperation(value = "Get audit logs by entity id (getAuditLogsByEntityId)",
  128 + notes = "Returns a page of audit logs by selected entity. " + PAGE_DATA_PARAMETERS,
  129 + produces = MediaType.APPLICATION_JSON_VALUE)
95 130 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
96 131 @RequestMapping(value = "/audit/logs/entity/{entityType}/{entityId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
97 132 @ResponseBody
98 133 public PageData<AuditLog> getAuditLogsByEntityId(
  134 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION)
99 135 @PathVariable("entityType") String strEntityType,
  136 + @ApiParam(value = ENTITY_ID_DESCRIPTION)
100 137 @PathVariable("entityId") String strEntityId,
  138 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
101 139 @RequestParam int pageSize,
  140 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
102 141 @RequestParam int page,
  142 + @ApiParam(value = "The case insensitive 'startsWith' filter based on the entity name.")
103 143 @RequestParam(required = false) String textSearch,
  144 + @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
104 145 @RequestParam(required = false) String sortProperty,
  146 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
105 147 @RequestParam(required = false) String sortOrder,
  148 + @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
106 149 @RequestParam(required = false) Long startTime,
  150 + @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
107 151 @RequestParam(required = false) Long endTime,
  152 + @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
108 153 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
109 154 try {
110 155 checkParameter("EntityId", strEntityId);
... ... @@ -118,17 +163,27 @@ public class AuditLogController extends BaseController {
118 163 }
119 164 }
120 165
  166 + @ApiOperation(value = "Get all audit logs (getAuditLogs)",
  167 + notes = "Returns a page of all audit logs. " + PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
121 168 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
122 169 @RequestMapping(value = "/audit/logs", params = {"pageSize", "page"}, method = RequestMethod.GET)
123 170 @ResponseBody
124 171 public PageData<AuditLog> getAuditLogs(
  172 + @ApiParam(value = PAGE_SIZE_DESCRIPTION)
125 173 @RequestParam int pageSize,
  174 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
126 175 @RequestParam int page,
  176 + @ApiParam(value = "The case insensitive 'startsWith' filter based on any name like 'Device', 'Asset', 'Customer' etc.")
127 177 @RequestParam(required = false) String textSearch,
  178 + @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
128 179 @RequestParam(required = false) String sortProperty,
  180 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
129 181 @RequestParam(required = false) String sortOrder,
  182 + @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
130 183 @RequestParam(required = false) Long startTime,
  184 + @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
131 185 @RequestParam(required = false) Long endTime,
  186 + @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
132 187 @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
133 188 try {
134 189 TenantId tenantId = getCurrentUser().getTenantId();
... ...
... ... @@ -162,6 +162,7 @@ public abstract class BaseController {
162 162 public static final String TENANT_ID_PARAM_DESCRIPTION = "A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
163 163 public static final String EDGE_ID_PARAM_DESCRIPTION = "A string value representing the edge id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
164 164 public static final String CUSTOMER_ID_PARAM_DESCRIPTION = "A string value representing the customer id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  165 + public static final String USER_ID_PARAM_DESCRIPTION = "A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
165 166
166 167 protected final String PAGE_SIZE_DESCRIPTION = "Maximum amount of entities in a one page";
167 168 protected final String PAGE_NUMBER_DESCRIPTION = "Sequence number of page starting from 0";
... ... @@ -174,7 +175,8 @@ public abstract class BaseController {
174 175 protected final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
175 176 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. ";
176 177
177   -
  178 + protected static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'";
  179 + protected static final String ENTITY_ID_DESCRIPTION = "A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
178 180
179 181 public static final String INCORRECT_TENANT_ID = "Incorrect tenantId ";
180 182 protected static final String DEFAULT_DASHBOARD = "defaultDashboardId";
... ...
... ... @@ -16,24 +16,37 @@
16 16 package org.thingsboard.server.common.data.audit;
17 17
18 18 import com.fasterxml.jackson.databind.JsonNode;
  19 +import io.swagger.annotations.ApiModel;
  20 +import io.swagger.annotations.ApiModelProperty;
19 21 import lombok.Data;
20 22 import lombok.EqualsAndHashCode;
21 23 import org.thingsboard.server.common.data.BaseData;
22 24 import org.thingsboard.server.common.data.id.*;
23 25
  26 +@ApiModel
24 27 @EqualsAndHashCode(callSuper = true)
25 28 @Data
26 29 public class AuditLog extends BaseData<AuditLogId> {
27 30
  31 + @ApiModelProperty(position = 3, value = "JSON object with Tenant Id.", readOnly = true)
28 32 private TenantId tenantId;
  33 + @ApiModelProperty(position = 2, value = "JSON object with Customer Id.", readOnly = true)
29 34 private CustomerId customerId;
  35 + @ApiModelProperty(position = 3, value = "JSON object with Entity id.", readOnly = true)
30 36 private EntityId entityId;
  37 + @ApiModelProperty(position = 4, value = "Entity Name", example = "Thermometer", readOnly = true)
31 38 private String entityName;
  39 + @ApiModelProperty(position = 5, value = "JSON object with User id.", readOnly = true)
32 40 private UserId userId;
  41 + @ApiModelProperty(position = 6, value = "Unique User Name in scope of Administrator.", example = "Tenant", readOnly = true)
33 42 private String userName;
  43 + @ApiModelProperty(position = 7, value = "String represented Action type.", readOnly = true)
34 44 private ActionType actionType;
  45 + @ApiModelProperty(position = 8, value = "JsonNode represented action data.", readOnly = true)
35 46 private JsonNode actionData;
  47 + @ApiModelProperty(position = 9, value = "string", example = "SUCCESS", allowableValues = "SUCCESS,FAILURE", readOnly = true)
36 48 private ActionStatus actionStatus;
  49 + @ApiModelProperty(position = 10, value = "Action failure details info", readOnly = true)
37 50 private String actionFailureDetails;
38 51
39 52 public AuditLog() {
... ...