Merge pull request #15169 from thingsboard/fix/additionalinfo-swagger-schemas

API documentation improvements

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

@@ -608,12 +608,13 @@ public class TelemetryController extends BaseController {
 
     @ApiOperation(value = "Delete entity attributes (deleteEntityAttributes)",
             notes = "Delete entity attributes using provided Entity Id, scope and a list of keys. " +
+                    "This operation is idempotent: keys that do not exist are silently ignored and the response is still 200 OK. " +
                     INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
     @Parameters({
             @Parameter(name = "key", description = "Repeatable key query parameter (alternative to comma-separated 'keys')", in = ParameterIn.QUERY, required = false, array = @ArraySchema(schema = @Schema(type = "string")))
     })
     @ApiResponses(value = {
-            @ApiResponse(responseCode = "200", description = "Entity attributes was removed for the selected keys in the request. " +
+            @ApiResponse(responseCode = "200", description = "Entity attributes were removed for the selected keys in the request (keys that did not exist are silently ignored). " +
                     "Platform creates an audit log event about entity attributes removal with action type 'ATTRIBUTES_DELETED'."),
             @ApiResponse(responseCode = "400", description = "Platform returns a bad request in case if keys or scope are not specified."),
             @ApiResponse(responseCode = "401", description = "User is not authorized to delete entity attributes for selected entity. Most likely, User belongs to different Customer or Tenant."),

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

@@ -140,7 +140,12 @@ public class Customer extends ContactBased<CustomerId> implements HasTenantId, E
         return super.getEmail();
     }
 
-    @Schema(description = "Additional parameters of the device",implementation = com.fasterxml.jackson.databind.JsonNode.class)
+    @Schema(description = "Additional parameters of the customer. " +
+            "May include: 'description' (string), 'homeDashboardId' (string, UUID of the home dashboard), " +
+            "'homeDashboardHideToolbar' (boolean, whether to hide the dashboard toolbar), " +
+            "'isPublic' (boolean, whether this is a public customer).",
+            implementation = com.fasterxml.jackson.databind.JsonNode.class,
+            example = "{\"description\":\"Regional customer\",\"homeDashboardId\":\"784f394c-42b6-435a-983c-b7beff2784f9\",\"homeDashboardHideToolbar\":false,\"isPublic\":false}")
     @Override
     public JsonNode getAdditionalInfo() {
         return super.getAdditionalInfo();

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

@@ -231,7 +231,12 @@ public class Device extends BaseDataWithAdditionalInfo<DeviceId> implements HasL
         this.softwareId = softwareId;
     }
 
-    @Schema(description = "Additional parameters of the device",implementation = com.fasterxml.jackson.databind.JsonNode.class)
+    @Schema(description = "Additional parameters of the device. " +
+            "May include: 'gateway' (boolean, whether the device is a gateway), " +
+            "'description' (string), " +
+            "'lastConnectedGateway' (string, UUID of the last gateway that connected this device).",
+            implementation = com.fasterxml.jackson.databind.JsonNode.class,
+            example = "{\"gateway\":false,\"description\":\"Temperature sensor\",\"lastConnectedGateway\":\"784f394c-42b6-435a-983c-b7beff2784f9\"}")
     @Override
     public JsonNode getAdditionalInfo() {
         return super.getAdditionalInfo();

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

@@ -116,7 +116,10 @@ public class EntityView extends BaseDataWithAdditionalInfo<EntityViewId>
         return super.getCreatedTime();
     }
 
-    @Schema(description = "Additional parameters of the device", implementation = com.fasterxml.jackson.databind.JsonNode.class)
+    @Schema(description = "Additional parameters of the entity view. " +
+            "May include: 'description' (string).",
+            implementation = com.fasterxml.jackson.databind.JsonNode.class,
+            example = "{\"description\":\"Temperature readings view\"}")
     @Override
     public JsonNode getAdditionalInfo() {
         return super.getAdditionalInfo();

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

@@ -164,7 +164,11 @@ public class Tenant extends ContactBased<TenantId> implements HasTenantId, HasTi
         return super.getEmail();
     }
 
-    @Schema(description = "Additional parameters of the device", implementation = com.fasterxml.jackson.databind.JsonNode.class)
+    @Schema(description = "Additional parameters of the tenant. " +
+            "May include: 'description' (string), 'homeDashboardId' (string, UUID of the home dashboard), " +
+            "'homeDashboardHideToolbar' (boolean, whether to hide the dashboard toolbar).",
+            implementation = com.fasterxml.jackson.databind.JsonNode.class,
+            example = "{\"description\":\"Main tenant\",\"homeDashboardId\":\"784f394c-42b6-435a-983c-b7beff2784f9\",\"homeDashboardHideToolbar\":true}")
     @Override
     public JsonNode getAdditionalInfo() {
         return super.getAdditionalInfo();

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

@@ -161,7 +161,16 @@ public class User extends BaseDataWithAdditionalInfo<UserId> implements HasName,
         this.phone = phone;
     }
 
-    @Schema(description = "Additional parameters of the user", implementation = com.fasterxml.jackson.databind.JsonNode.class)
+    @Schema(description = "Additional parameters of the user. " +
+            "May include: 'defaultDashboardId' (string, UUID of the default dashboard), " +
+            "'defaultDashboardFullscreen' (boolean), " +
+            "'homeDashboardId' (string, UUID of the home dashboard), " +
+            "'homeDashboardHideToolbar' (boolean), " +
+            "'lang' (string, user locale, e.g. 'en_US'), " +
+            "'authProviderName' (string, name of the authentication provider).",
+            implementation = com.fasterxml.jackson.databind.JsonNode.class,
+            example = "{\"defaultDashboardId\":\"784f394c-42b6-435a-983c-b7beff2784f9\",\"defaultDashboardFullscreen\":false," +
+                    "\"homeDashboardId\":\"784f394c-42b6-435a-983c-b7beff2784f9\",\"homeDashboardHideToolbar\":true,\"lang\":\"en_US\"}")
     @Override
     public JsonNode getAdditionalInfo() {
         return super.getAdditionalInfo();

common/data/src/main/java/org/thingsboard/server/common/data/asset/Asset.java

@@ -169,7 +169,10 @@ public class Asset extends BaseDataWithAdditionalInfo<AssetId> implements HasLab
         this.assetProfileId = assetProfileId;
     }
 
-    @Schema(description = "Additional parameters of the asset",implementation = com.fasterxml.jackson.databind.JsonNode.class)
+    @Schema(description = "Additional parameters of the asset. " +
+            "May include: 'description' (string).",
+            implementation = com.fasterxml.jackson.databind.JsonNode.class,
+            example = "{\"description\":\"Building A asset\"}")
     @Override
     public JsonNode getAdditionalInfo() {
         return super.getAdditionalInfo();

common/data/src/main/java/org/thingsboard/server/common/data/audit/ActionType.java

@@ -22,42 +22,203 @@ import java.util.Optional;
 
 public enum ActionType {
 
-    ADDED(TbMsgType.ENTITY_CREATED), // log entity
-    DELETED(TbMsgType.ENTITY_DELETED), // log string id
-    UPDATED(TbMsgType.ENTITY_UPDATED), // log entity
-    ATTRIBUTES_UPDATED(TbMsgType.ATTRIBUTES_UPDATED), // log attributes/values
-    ATTRIBUTES_DELETED(TbMsgType.ATTRIBUTES_DELETED), // log attributes
-    TIMESERIES_UPDATED(TbMsgType.TIMESERIES_UPDATED), // log timeseries update
-    TIMESERIES_DELETED(TbMsgType.TIMESERIES_DELETED), // log timeseries
-    RPC_CALL, // log method and params
-    CREDENTIALS_UPDATED, // log new credentials
-    ASSIGNED_TO_CUSTOMER(TbMsgType.ENTITY_ASSIGNED), // log customer name
-    UNASSIGNED_FROM_CUSTOMER(TbMsgType.ENTITY_UNASSIGNED), // log customer name
-    ACTIVATED, // log string id
-    SUSPENDED, // log string id
-    CREDENTIALS_READ(true), // log device id
-    ATTRIBUTES_READ(true), // log attributes
+    /**
+     * Entity created. Pushes {@link TbMsgType#ENTITY_CREATED} to rule engine.
+     * Audit log payload: full entity JSON.
+     */
+    ADDED(TbMsgType.ENTITY_CREATED),
+    /**
+     * Entity deleted. Pushes {@link TbMsgType#ENTITY_DELETED} to rule engine.
+     * Audit log payload: entity string id.
+     */
+    DELETED(TbMsgType.ENTITY_DELETED),
+    /**
+     * Entity updated. Pushes {@link TbMsgType#ENTITY_UPDATED} to rule engine.
+     * Audit log payload: full entity JSON.
+     */
+    UPDATED(TbMsgType.ENTITY_UPDATED),
+    /**
+     * Server-side or shared attributes updated via API.
+     * Pushes {@link TbMsgType#ATTRIBUTES_UPDATED} to rule engine.
+     * Rule engine msg metadata includes {@code scope} ({@code SERVER_SCOPE} or {@code SHARED_SCOPE}).
+     * Rule engine msg data: key-value pairs of the updated attributes.
+     * Audit log payload: updated attributes and their values.
+     */
+    ATTRIBUTES_UPDATED(TbMsgType.ATTRIBUTES_UPDATED),
+    /**
+     * Attributes deleted via API.
+     * Pushes {@link TbMsgType#ATTRIBUTES_DELETED} to rule engine.
+     * Rule engine msg metadata includes {@code scope} ({@code SERVER_SCOPE} or {@code SHARED_SCOPE}).
+     * Rule engine msg data: {@code {"attributes": ["key1", "key2"]}}.
+     * Audit log payload: list of deleted attribute keys.
+     */
+    ATTRIBUTES_DELETED(TbMsgType.ATTRIBUTES_DELETED),
+    /**
+     * Timeseries data saved via API (not from device transport).
+     * Pushes {@link TbMsgType#TIMESERIES_UPDATED} to rule engine.
+     * Rule engine msg data: {@code {"timeseries": [{"ts": ..., "values": {...}}, ...]}}.
+     * Audit log payload: timeseries entries.
+     */
+    TIMESERIES_UPDATED(TbMsgType.TIMESERIES_UPDATED),
+    /**
+     * Timeseries data deleted via API.
+     * Pushes {@link TbMsgType#TIMESERIES_DELETED} to rule engine.
+     * Rule engine msg data: {@code {"timeseries": ["key1", ...], "startTs": ..., "endTs": ...}}.
+     * Audit log payload: deleted timeseries keys.
+     */
+    TIMESERIES_DELETED(TbMsgType.TIMESERIES_DELETED),
+    /**
+     * RPC call to device. Does not push to rule engine (RPC has its own lifecycle messages).
+     * Audit log payload: RPC method and params.
+     */
+    RPC_CALL,
+    /**
+     * Device credentials updated. Does not push to rule engine.
+     * Audit log payload: new credentials value.
+     */
+    CREDENTIALS_UPDATED,
+    /**
+     * Entity assigned to a customer. Pushes {@link TbMsgType#ENTITY_ASSIGNED} to rule engine.
+     * Rule engine msg metadata includes {@code assignedCustomerId} and {@code assignedCustomerName}.
+     * Audit log payload: customer name.
+     */
+    ASSIGNED_TO_CUSTOMER(TbMsgType.ENTITY_ASSIGNED),
+    /**
+     * Entity unassigned from a customer. Pushes {@link TbMsgType#ENTITY_UNASSIGNED} to rule engine.
+     * Rule engine msg metadata includes {@code unassignedCustomerId} and {@code unassignedCustomerName}.
+     * Audit log payload: customer name.
+     */
+    UNASSIGNED_FROM_CUSTOMER(TbMsgType.ENTITY_UNASSIGNED),
+    /**
+     * User account or integration activated. Does not push to rule engine.
+     * Audit log payload: entity string id.
+     */
+    ACTIVATED,
+    /**
+     * User account or integration suspended. Does not push to rule engine.
+     * Audit log payload: entity string id.
+     */
+    SUSPENDED,
+    /**
+     * Device credentials read. Read-only action. Does not push to rule engine.
+     * Audit log payload: device id.
+     */
+    CREDENTIALS_READ(true),
+    /**
+     * Attributes read. Read-only action. Does not push to rule engine.
+     * Audit log payload: attribute keys read.
+     */
+    ATTRIBUTES_READ(true),
+    /**
+     * Relation created or updated. Pushes {@link TbMsgType#RELATION_ADD_OR_UPDATE} to rule engine.
+     * Rule engine msg data: relation JSON ({@code from}, {@code to}, {@code type}, {@code typeGroup}).
+     */
     RELATION_ADD_OR_UPDATE(TbMsgType.RELATION_ADD_OR_UPDATE),
+    /**
+     * Relation deleted. Pushes {@link TbMsgType#RELATION_DELETED} to rule engine.
+     * Rule engine msg data: relation JSON ({@code from}, {@code to}, {@code type}, {@code typeGroup}).
+     */
     RELATION_DELETED(TbMsgType.RELATION_DELETED),
+    /**
+     * All relations for an entity deleted. Pushes {@link TbMsgType#RELATIONS_DELETED} to rule engine.
+     * Rule engine msg data: empty JSON object.
+     */
     RELATIONS_DELETED(TbMsgType.RELATIONS_DELETED),
-    REST_API_RULE_ENGINE_CALL, // log call to rule engine from REST API
+    /**
+     * REST API call to rule engine. Does not push to rule engine directly
+     * (the REST controller creates a {@link TbMsgType#REST_API_REQUEST} message itself).
+     * Audit log payload: call details.
+     */
+    REST_API_RULE_ENGINE_CALL,
+    /**
+     * Alarm acknowledged by a user. Pushes {@link TbMsgType#ALARM_ACK} to rule engine.
+     * Rule engine msg data: full alarm JSON. Originator: alarm id.
+     */
     ALARM_ACK(TbMsgType.ALARM_ACK, true),
+    /**
+     * Alarm cleared by a user. Pushes {@link TbMsgType#ALARM_CLEAR} to rule engine.
+     * Rule engine msg data: full alarm JSON. Originator: alarm id.
+     */
     ALARM_CLEAR(TbMsgType.ALARM_CLEAR, true),
+    /**
+     * Alarm deleted by a user. Pushes {@link TbMsgType#ALARM_DELETE} to rule engine.
+     * Rule engine msg data: full alarm JSON. Originator: alarm id.
+     */
     ALARM_DELETE(TbMsgType.ALARM_DELETE, true),
+    /**
+     * Alarm assigned to a user. Pushes {@link TbMsgType#ALARM_ASSIGNED} to rule engine.
+     * Rule engine msg data: full alarm JSON. Originator: alarm id.
+     */
     ALARM_ASSIGNED(TbMsgType.ALARM_ASSIGNED, true),
+    /**
+     * Alarm unassigned from a user. Pushes {@link TbMsgType#ALARM_UNASSIGNED} to rule engine.
+     * Rule engine msg data: full alarm JSON. Originator: alarm id.
+     */
     ALARM_UNASSIGNED(TbMsgType.ALARM_UNASSIGNED, true),
+    /**
+     * User logged in. Does not push to rule engine.
+     */
     LOGIN,
+    /**
+     * User logged out. Does not push to rule engine.
+     */
     LOGOUT,
+    /**
+     * User account locked out due to too many failed login attempts. Does not push to rule engine.
+     */
     LOCKOUT,
+    /**
+     * Entity assigned from another tenant (incoming side of cross-tenant transfer).
+     * Pushes {@link TbMsgType#ENTITY_ASSIGNED_FROM_TENANT} to rule engine.
+     * Rule engine msg metadata includes {@code assignedFromTenantId} and {@code assignedFromTenantName}.
+     */
     ASSIGNED_FROM_TENANT(TbMsgType.ENTITY_ASSIGNED_FROM_TENANT),
+    /**
+     * Entity assigned to another tenant (outgoing side of cross-tenant transfer).
+     * Pushes {@link TbMsgType#ENTITY_ASSIGNED_TO_TENANT} to rule engine.
+     * Rule engine msg metadata includes {@code assignedToTenantId} and {@code assignedToTenantName}.
+     */
     ASSIGNED_TO_TENANT(TbMsgType.ENTITY_ASSIGNED_TO_TENANT),
+    /**
+     * Device provisioned successfully. Pushes {@link TbMsgType#PROVISION_SUCCESS} to rule engine.
+     * Rule engine msg data: full device JSON.
+     */
     PROVISION_SUCCESS(TbMsgType.PROVISION_SUCCESS),
+    /**
+     * Device provisioning failed. Pushes {@link TbMsgType#PROVISION_FAILURE} to rule engine.
+     * Rule engine msg data: full device JSON.
+     */
     PROVISION_FAILURE(TbMsgType.PROVISION_FAILURE),
-    ASSIGNED_TO_EDGE(TbMsgType.ENTITY_ASSIGNED_TO_EDGE), // log edge name
+    /**
+     * Entity assigned to an Edge instance. Pushes {@link TbMsgType#ENTITY_ASSIGNED_TO_EDGE} to rule engine.
+     * Rule engine msg metadata includes {@code assignedEdgeId} and {@code assignedEdgeName}.
+     * Audit log payload: edge name.
+     */
+    ASSIGNED_TO_EDGE(TbMsgType.ENTITY_ASSIGNED_TO_EDGE),
+    /**
+     * Entity unassigned from an Edge instance. Pushes {@link TbMsgType#ENTITY_UNASSIGNED_FROM_EDGE} to rule engine.
+     * Rule engine msg metadata includes {@code unassignedEdgeId} and {@code unassignedEdgeName}.
+     */
     UNASSIGNED_FROM_EDGE(TbMsgType.ENTITY_UNASSIGNED_FROM_EDGE),
+    /**
+     * Comment added to an alarm. Pushes {@link TbMsgType#COMMENT_CREATED} to rule engine.
+     * Rule engine msg metadata includes {@code comment} (JSON string of the AlarmComment object).
+     * Rule engine msg data: full alarm JSON. Originator: alarm id.
+     */
     ADDED_COMMENT(TbMsgType.COMMENT_CREATED),
+    /**
+     * Alarm comment updated. Pushes {@link TbMsgType#COMMENT_UPDATED} to rule engine.
+     * Rule engine msg metadata includes {@code comment} (JSON string of the AlarmComment object).
+     * Rule engine msg data: full alarm JSON. Originator: alarm id.
+     */
     UPDATED_COMMENT(TbMsgType.COMMENT_UPDATED),
+    /**
+     * Alarm comment deleted. Does not push to rule engine.
+     */
     DELETED_COMMENT,
+    /**
+     * SMS sent. Does not push to rule engine.
+     */
     SMS_SENT;
 
     @Getter

common/data/src/main/java/org/thingsboard/server/common/data/edge/Edge.java

@@ -15,6 +15,7 @@
  */
 package org.thingsboard.server.common.data.edge;
 
+import com.fasterxml.jackson.databind.JsonNode;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
@@ -153,4 +154,13 @@ public class Edge extends BaseDataWithAdditionalInfo<EdgeId> implements HasLabel
         return this.secret;
     }
 
+    @Schema(description = "Additional parameters of the edge. " +
+            "May include: 'description' (string).",
+            implementation = com.fasterxml.jackson.databind.JsonNode.class,
+            example = "{\"description\":\"Edge at location A\"}")
+    @Override
+    public JsonNode getAdditionalInfo() {
+        return super.getAdditionalInfo();
+    }
+
 }

common/data/src/main/java/org/thingsboard/server/common/data/relation/EntityRelation.java

@@ -103,7 +103,9 @@ public class EntityRelation implements HasVersion, Serializable, EdqsObject {
         this.version = entityRelation.getVersion();
     }
 
-    @Schema(description = "Additional parameters of the relation", implementation = JsonNode.class)
+    @Schema(description = "Additional parameters of the relation.",
+            implementation = JsonNode.class,
+            example = "{\"description\":\"Power supply connection\"}")
     public JsonNode getAdditionalInfo() {
         return BaseDataWithAdditionalInfo.getJson(() -> additionalInfo, () -> additionalInfoBytes);
     }

common/data/src/main/java/org/thingsboard/server/common/data/rule/RuleNode.java

@@ -105,7 +105,12 @@ public class RuleNode extends BaseDataWithAdditionalInfo<RuleNodeId> implements
         return super.getCreatedTime();
     }
 
-    @Schema(description = "Additional parameters of the rule node. Contains 'layoutX' and 'layoutY' properties for visualization.", implementation = JsonNode.class)
+    @Schema(description = "Additional parameters of the rule node. " +
+            "May include: 'layoutX' (number, X coordinate for visualization), " +
+            "'layoutY' (number, Y coordinate for visualization), " +
+            "'description' (string).",
+            implementation = JsonNode.class,
+            example = "{\"layoutX\":320,\"layoutY\":160,\"description\":\"Filter temperature data\"}")
     @Override
     public JsonNode getAdditionalInfo() {
         return super.getAdditionalInfo();