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

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
Mariia Synelnyk · GitHub
1 parent e6e05c9b
Showing 3 changed files with 71 additions and 1 deletions
application/src/main/java/org/thingsboard/server/controller/AuditLogController.java
application/src/main/java/org/thingsboard/server/controller/BaseController.java
common/data/src/main/java/org/thingsboard/server/common/data/audit/AuditLog.java
--- a/application/src/main/java/org/thingsboard/server/controller/AuditLogController.java
View file @a126b88
+++ b/application/src/main/java/org/thingsboard/server/controller/AuditLogController.java
View file @a126b88
@@ -15,7 +15,10 @@
  */
 package org.thingsboard.server.controller;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import org.apache.commons.lang3.StringUtils;
+import org.springframework.http.MediaType;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -44,18 +47,35 @@ import java.util.stream.Collectors;
 @RequestMapping("/api")
 public class AuditLogController extends BaseController {
+    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. " +
+            "For example, 'ADDED,DELETED,UPDATED,LOGIN,LOGOUT'.";
+    protected final String SORT_AUDIT_LOG_PROPERTY_DESCRIPTION = "Property of logs to sort by";
+    protected final String SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES = "createdTime, entityName, entityType, user, type, status";
+
+    @ApiOperation(value = "Get audit logs by customer id (getAuditLogsByCustomerId)",
+            notes = "Returns a page of audit logs by selected customer. " + PAGE_DATA_PARAMETERS,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/audit/logs/customer/{customerId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
     public PageData<AuditLog> getAuditLogsByCustomerId(
+            @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION)
             @PathVariable("customerId") String strCustomerId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
             @RequestParam int page,
+            @ApiParam(value = "The case insensitive 'startsWith' filter based on the customer name.")
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortOrder,
+            @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long startTime,
+            @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long endTime,
+            @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
             @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
         try {
             checkParameter("CustomerId", strCustomerId);
@@ -68,18 +88,30 @@ public class AuditLogController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get audit logs by user id (getAuditLogsByUserId)",
+            notes = "Returns a page of audit logs by selected user. " + PAGE_DATA_PARAMETERS,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/audit/logs/user/{userId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
     public PageData<AuditLog> getAuditLogsByUserId(
+            @ApiParam(value = USER_ID_PARAM_DESCRIPTION)
             @PathVariable("userId") String strUserId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
             @RequestParam int page,
+            @ApiParam(value = "The case insensitive 'startsWith' filter based on the user name.")
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortOrder,
+            @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long startTime,
+            @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long endTime,
+            @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
             @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
         try {
             checkParameter("UserId", strUserId);
@@ -92,19 +124,32 @@ public class AuditLogController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get audit logs by entity id (getAuditLogsByEntityId)",
+            notes = "Returns a page of audit logs by selected entity. " + PAGE_DATA_PARAMETERS,
+            produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/audit/logs/entity/{entityType}/{entityId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
     public PageData<AuditLog> getAuditLogsByEntityId(
+            @ApiParam(value = ENTITY_TYPE_DESCRIPTION)
             @PathVariable("entityType") String strEntityType,
+            @ApiParam(value = ENTITY_ID_DESCRIPTION)
             @PathVariable("entityId") String strEntityId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
             @RequestParam int page,
+            @ApiParam(value = "The case insensitive 'startsWith' filter based on the entity name.")
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortOrder,
+            @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long startTime,
+            @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long endTime,
+            @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
             @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
         try {
             checkParameter("EntityId", strEntityId);
@@ -118,17 +163,27 @@ public class AuditLogController extends BaseController {
         }
     }
+    @ApiOperation(value = "Get all audit logs (getAuditLogs)",
+            notes = "Returns a page of all audit logs. " + PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/audit/logs", params = {"pageSize", "page"}, method = RequestMethod.GET)
     @ResponseBody
     public PageData<AuditLog> getAuditLogs(
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION)
             @RequestParam int page,
+            @ApiParam(value = "The case insensitive 'startsWith' filter based on any name like 'Device', 'Asset', 'Customer' etc.")
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_AUDIT_LOG_PROPERTY_DESCRIPTION, allowableValues = SORT_AUDIT_LOG_PROPERTY_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortProperty,
+            @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
             @RequestParam(required = false) String sortOrder,
+            @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long startTime,
+            @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
             @RequestParam(required = false) Long endTime,
+            @ApiParam(value = AUDIT_LOG_ACTION_TYPES_DESCRIPTION)
             @RequestParam(name = "actionTypes", required = false) String actionTypesStr) throws ThingsboardException {
         try {
             TenantId tenantId = getCurrentUser().getTenantId();
--- a/application/src/main/java/org/thingsboard/server/controller/BaseController.java
View file @a126b88
+++ b/application/src/main/java/org/thingsboard/server/controller/BaseController.java
View file @a126b88
@@ -162,6 +162,7 @@ public abstract class BaseController {
     public static final String TENANT_ID_PARAM_DESCRIPTION = "A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String EDGE_ID_PARAM_DESCRIPTION = "A string value representing the edge id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String CUSTOMER_ID_PARAM_DESCRIPTION = "A string value representing the customer id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
+    public static final String USER_ID_PARAM_DESCRIPTION = "A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     protected final String PAGE_SIZE_DESCRIPTION = "Maximum amount of entities in a one page";
     protected final String PAGE_NUMBER_DESCRIPTION = "Sequence number of page starting from 0";
@@ -174,7 +175,8 @@ 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 static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'";
+    protected static final String ENTITY_ID_DESCRIPTION = "A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
     public static final String INCORRECT_TENANT_ID = "Incorrect tenantId ";
     protected static final String DEFAULT_DASHBOARD = "defaultDashboardId";
--- a/common/data/src/main/java/org/thingsboard/server/common/data/audit/AuditLog.java
View file @a126b88
+++ b/common/data/src/main/java/org/thingsboard/server/common/data/audit/AuditLog.java
View file @a126b88
@@ -16,24 +16,37 @@
 package org.thingsboard.server.common.data.audit;
 import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import org.thingsboard.server.common.data.BaseData;
 import org.thingsboard.server.common.data.id.*;
+@ApiModel
 @EqualsAndHashCode(callSuper = true)
 @Data
 public class AuditLog extends BaseData<AuditLogId> {
+    @ApiModelProperty(position = 3, value = "JSON object with Tenant Id.", readOnly = true)
     private TenantId tenantId;
+    @ApiModelProperty(position = 2, value = "JSON object with Customer Id.", readOnly = true)
     private CustomerId customerId;
+    @ApiModelProperty(position = 3, value = "JSON object with Entity id.", readOnly = true)
     private EntityId entityId;
+    @ApiModelProperty(position = 4, value = "Entity Name", example = "Thermometer", readOnly = true)
     private String entityName;
+    @ApiModelProperty(position = 5, value = "JSON object with User id.", readOnly = true)
     private UserId userId;
+    @ApiModelProperty(position = 6, value = "Unique User Name in scope of Administrator.", example = "Tenant", readOnly = true)
     private String userName;
+    @ApiModelProperty(position = 7, value = "String represented Action type.", readOnly = true)
     private ActionType actionType;
+    @ApiModelProperty(position = 8, value = "JsonNode represented action data.", readOnly = true)
     private JsonNode actionData;
+    @ApiModelProperty(position = 9, value = "string", example = "SUCCESS", allowableValues = "SUCCESS,FAILURE", readOnly = true)
     private ActionStatus actionStatus;
+    @ApiModelProperty(position = 10, value = "Action failure details info", readOnly = true)
     private String actionFailureDetails;
     public AuditLog() {