swagger description for event controller

application/src/main/java/org/thingsboard/server/controller/BaseController.java

@@ -169,6 +169,8 @@ public abstract class BaseController {
     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 ASSET_ID_PARAM_DESCRIPTION = "A string value representing the asset id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
 
+    protected static final String ENTITY_ID_PARAM_DESCRIPTION = "A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
+    protected static final String ENTITY_TYPE_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'";
 
     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";
@@ -179,11 +181,13 @@ public abstract class BaseController {
     protected final String DASHBOARD_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the dashboard title.";
     protected final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device name.";
     protected final String CUSTOMER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the customer title.";
+    protected final String EVENT_TEXT_SEARCH_DESCRIPTION = "The value is not used in searching.";
     protected final String SORT_PROPERTY_DESCRIPTION = "Property of entity to sort by";
     protected final String DASHBOARD_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title";
     protected final String CUSTOMER_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, email, country, city";
     protected final String DEVICE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, deviceProfileName, label, customerTitle";
     protected final String ASSET_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
+    protected final String EVENT_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, id";
     protected final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESC (DESCENDING)";
     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. ";
@@ -193,6 +197,9 @@ public abstract class BaseController {
     protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name.";
     protected final String ASSET_NAME_DESCRIPTION = "A string value representing the Asset name.";
 
+    protected final String EVENT_START_TIME_DESCRIPTION = "Timestamp. Events with creation time before it won't be queried.";
+    protected final String EVENT_END_TIME_DESCRIPTION = "Timestamp. Events with creation time after it won't be queried.";
+
     public static final String INCORRECT_TENANT_ID = "Incorrect tenantId ";
     protected static final String DEFAULT_DASHBOARD = "defaultDashboardId";
     protected static final String HOME_DASHBOARD = "homeDashboardId";

application/src/main/java/org/thingsboard/server/controller/EventController.java

@@ -15,7 +15,10 @@
  */
 package org.thingsboard.server.controller;
 
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import org.springframework.beans.factory.annotation.Autowired;
+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.RequestBody;
@@ -45,20 +48,34 @@ public class EventController extends BaseController {
     @Autowired
     private EventService eventService;
 
+    @ApiOperation(value = "Get Events (getEvents)",
+            notes = "Returns a page of events for specified entity by specifying event type." +
+                    PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/events/{entityType}/{entityId}/{eventType}", method = RequestMethod.GET)
     @ResponseBody
     public PageData<Event> getEvents(
+            @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true)
             @PathVariable("entityType") String strEntityType,
+            @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true)
             @PathVariable("entityId") String strEntityId,
+            @ApiParam(value = "A string value representing event type", example = "STATS", required = true)
             @PathVariable("eventType") String eventType,
+            @ApiParam(value = TENANT_ID_PARAM_DESCRIPTION, required = true)
             @RequestParam("tenantId") String strTenantId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
+            @ApiParam(value = EVENT_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EVENT_SORT_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 = EVENT_START_TIME_DESCRIPTION)
             @RequestParam(required = false) Long startTime,
+            @ApiParam(value = EVENT_END_TIME_DESCRIPTION)
             @RequestParam(required = false) Long endTime) throws ThingsboardException {
         checkParameter("EntityId", strEntityId);
         checkParameter("EntityType", strEntityType);
@@ -74,19 +91,32 @@ public class EventController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Events (getEvents)",
+            notes = "Returns a page of events for specified entity." +
+                    PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/events/{entityType}/{entityId}", method = RequestMethod.GET)
     @ResponseBody
     public PageData<Event> getEvents(
+            @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true)
             @PathVariable("entityType") String strEntityType,
+            @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true)
             @PathVariable("entityId") String strEntityId,
+            @ApiParam(value = TENANT_ID_PARAM_DESCRIPTION, required = true)
             @RequestParam("tenantId") String strTenantId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
+            @ApiParam(value = EVENT_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EVENT_SORT_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 = EVENT_START_TIME_DESCRIPTION)
             @RequestParam(required = false) Long startTime,
+            @ApiParam(value = EVENT_END_TIME_DESCRIPTION)
             @RequestParam(required = false) Long endTime) throws ThingsboardException {
         checkParameter("EntityId", strEntityId);
         checkParameter("EntityType", strEntityType);
@@ -104,20 +134,34 @@ public class EventController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Get Events (getEvents)",
+            notes = "Returns a page of events for specified entity by specifying event filter." +
+                    PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
     @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
     @RequestMapping(value = "/events/{entityType}/{entityId}", method = RequestMethod.POST)
     @ResponseBody
     public PageData<Event> getEvents(
+            @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true)
             @PathVariable("entityType") String strEntityType,
+            @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true)
             @PathVariable("entityId") String strEntityId,
+            @ApiParam(value = TENANT_ID_PARAM_DESCRIPTION, required = true)
             @RequestParam("tenantId") String strTenantId,
+            @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
             @RequestParam int pageSize,
+            @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
             @RequestParam int page,
+            @ApiParam(value = "A JSON value representing the event filter.", required = true)
             @RequestBody EventFilter eventFilter,
+            @ApiParam(value = EVENT_TEXT_SEARCH_DESCRIPTION)
             @RequestParam(required = false) String textSearch,
+            @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = EVENT_SORT_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 = EVENT_START_TIME_DESCRIPTION)
             @RequestParam(required = false) Long startTime,
+            @ApiParam(value = EVENT_END_TIME_DESCRIPTION)
             @RequestParam(required = false) Long endTime) throws ThingsboardException {
         checkParameter("EntityId", strEntityId);
         checkParameter("EntityType", strEntityType);
@@ -127,7 +171,7 @@ public class EventController extends BaseController {
             EntityId entityId = EntityIdFactory.getByTypeAndId(strEntityType, strEntityId);
             checkEntityId(entityId, Operation.READ);
 
-            if(sortProperty != null && sortProperty.equals("createdTime") && eventFilter.hasFilterForJsonBody()) {
+            if (sortProperty != null && sortProperty.equals("createdTime") && eventFilter.hasFilterForJsonBody()) {
                 sortProperty = ModelConstants.CREATED_TIME_PROPERTY;
             }
 

common/data/src/main/java/org/thingsboard/server/common/data/Event.java

@@ -16,6 +16,8 @@
 package org.thingsboard.server.common.data;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.thingsboard.server.common.data.id.EntityId;
 import org.thingsboard.server.common.data.id.EventId;
@@ -25,12 +27,18 @@ import org.thingsboard.server.common.data.id.TenantId;
  * @author Andrew Shvayka
  */
 @Data
+@ApiModel
 public class Event extends BaseData<EventId> {
 
+    @ApiModelProperty(position = 1, value = "JSON object with Tenant Id.", readOnly = true)
     private TenantId tenantId;
+    @ApiModelProperty(position = 2, value = "Event type", example = "STATS")
     private String type;
+    @ApiModelProperty(position = 3, value = "string", example = "784f394c-42b6-435a-983c-b7beff2784f9")
     private String uid;
+    @ApiModelProperty(position = 4, value = "JSON object with Entity Id for which event is created.", readOnly = true)
     private EntityId entityId;
+    @ApiModelProperty(position = 5, value = "Event body.", dataType = "com.fasterxml.jackson.databind.JsonNode")
     private transient JsonNode body;
 
     public Event() {
@@ -45,4 +53,9 @@ public class Event extends BaseData<EventId> {
         super(event);
     }
 
+    @ApiModelProperty(position = 6, value = "Timestamp of the event creation, in milliseconds", example = "1609459200000", readOnly = true)
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
 }

common/data/src/main/java/org/thingsboard/server/common/data/event/DebugEvent.java

@@ -15,10 +15,12 @@
  */
 package org.thingsboard.server.common.data.event;
 
+import io.swagger.annotations.ApiModel;
 import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 
 @Data
+@ApiModel
 public abstract class DebugEvent implements EventFilter {
 
     private String msgDirectionType;

common/data/src/main/java/org/thingsboard/server/common/data/event/DebugRuleChainEventFilter.java

@@ -15,6 +15,9 @@
  */
 package org.thingsboard.server.common.data.event;
 
+import io.swagger.annotations.ApiModel;
+
+@ApiModel
 public class DebugRuleChainEventFilter extends DebugEvent {
     @Override
     public EventType getEventType() {

common/data/src/main/java/org/thingsboard/server/common/data/event/DebugRuleNodeEventFilter.java

@@ -15,6 +15,9 @@
  */
 package org.thingsboard.server.common.data.event;
 
+import io.swagger.annotations.ApiModel;
+
+@ApiModel
 public class DebugRuleNodeEventFilter extends DebugEvent {
     @Override
     public EventType getEventType() {

common/data/src/main/java/org/thingsboard/server/common/data/event/ErrorEventFilter.java

@@ -15,10 +15,12 @@
  */
 package org.thingsboard.server.common.data.event;
 
+import io.swagger.annotations.ApiModel;
 import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 
 @Data
+@ApiModel
 public class ErrorEventFilter implements EventFilter {
     private String server;
     private String method;

common/data/src/main/java/org/thingsboard/server/common/data/event/EventFilter.java

@@ -16,10 +16,11 @@
 package org.thingsboard.server.common.data.event;
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonSubTypes;
 import com.fasterxml.jackson.annotation.JsonTypeInfo;
+import io.swagger.annotations.ApiModel;
 
+@ApiModel
 @JsonTypeInfo(
         use = JsonTypeInfo.Id.NAME,
         include = JsonTypeInfo.As.PROPERTY,

common/data/src/main/java/org/thingsboard/server/common/data/event/LifeCycleEventFilter.java

@@ -15,10 +15,12 @@
  */
 package org.thingsboard.server.common.data.event;
 
+import io.swagger.annotations.ApiModel;
 import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 
 @Data
+@ApiModel
 public class LifeCycleEventFilter implements EventFilter {
     private String server;
     private String event;

common/data/src/main/java/org/thingsboard/server/common/data/event/StatisticsEventFilter.java

@@ -15,10 +15,12 @@
  */
 package org.thingsboard.server.common.data.event;
 
+import io.swagger.annotations.ApiModel;
 import lombok.Data;
 import org.thingsboard.server.common.data.StringUtils;
 
 @Data
+@ApiModel
 public class StatisticsEventFilter implements EventFilter {
     private String server;
     private Integer messagesProcessed;