Swagger annotations for saveDeviceCredentials

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

@@ -19,9 +19,15 @@ import com.google.common.util.concurrent.FutureCallback;
 import com.google.common.util.concurrent.Futures;
 import com.google.common.util.concurrent.ListenableFuture;
 import com.google.common.util.concurrent.MoreExecutors;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.Example;
+import io.swagger.annotations.ExampleProperty;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PathVariable;
@@ -301,10 +307,16 @@ public class DeviceController extends BaseController {
         }
     }
 
+    @ApiOperation(value = "Updates device credentials.", notes = "During device creation, platform generates random 'ACCESS_TOKEN' credentials. " +
+            "Use this method to update the device credentials. First use 'getDeviceCredentialsByDeviceId' to get the credentials id and value. " +
+            "Then use current method to update the credentials type and value. It is not possible to create multiple device credentials for the same device. " +
+            "The structure of device credentials id and value is simple for the 'ACCESS_TOKEN' but is much more complex for the 'MQTT_BASIC' or 'LWM2M_CREDENTIALS'.")
     @PreAuthorize("hasAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/device/credentials", method = RequestMethod.POST)
     @ResponseBody
-    public DeviceCredentials saveDeviceCredentials(@RequestBody DeviceCredentials deviceCredentials) throws ThingsboardException {
+    public DeviceCredentials saveDeviceCredentials(
+            @ApiParam(value = "A JSON value representing the device credentials.")
+            @RequestBody DeviceCredentials deviceCredentials) throws ThingsboardException {
         checkNotNull(deviceCredentials);
         try {
             Device device = checkDeviceId(deviceCredentials.getDeviceId(), Operation.WRITE_CREDENTIALS);

common/data/pom.xml

@@ -96,6 +96,10 @@
             <groupId>org.apache.commons</groupId>
             <artifactId>commons-lang3</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.swagger</groupId>
+            <artifactId>swagger-annotations</artifactId>
+        </dependency>
     </dependencies>
 
     <build>

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

@@ -17,6 +17,7 @@ package org.thingsboard.server.common.data;
 
 import java.io.Serializable;
 
+import io.swagger.annotations.ApiModelProperty;
 import org.thingsboard.server.common.data.id.IdBased;
 import org.thingsboard.server.common.data.id.UUIDBased;
 

common/data/src/main/java/org/thingsboard/server/common/data/id/DeviceId.java

@@ -20,8 +20,11 @@ import java.util.UUID;
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import org.thingsboard.server.common.data.EntityType;
 
+@ApiModel
 public class DeviceId extends UUIDBased implements EntityId {
 
     private static final long serialVersionUID = 1L;
@@ -35,8 +38,8 @@ public class DeviceId extends UUIDBased implements EntityId {
         return new DeviceId(UUID.fromString(deviceId));
     }
 
-    @JsonIgnore
     @Override
+    @ApiModelProperty(position = 2, required = true, value = "string", example = "DEVICE", allowableValues = "DEVICE")
     public EntityType getEntityType() {
         return EntityType.DEVICE;
     }

common/data/src/main/java/org/thingsboard/server/common/data/id/EntityId.java

@@ -18,6 +18,7 @@ package org.thingsboard.server.common.data.id;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import io.swagger.annotations.ApiModelProperty;
 import org.thingsboard.server.common.data.EntityType;
 
 import java.io.Serializable;

common/data/src/main/java/org/thingsboard/server/common/data/id/UUIDBased.java

@@ -15,9 +15,13 @@
  */
 package org.thingsboard.server.common.data.id;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+
 import java.io.Serializable;
 import java.util.UUID;
 
+@ApiModel
 public abstract class UUIDBased implements HasUUID, Serializable {
 
     private static final long serialVersionUID = 1L;
@@ -33,6 +37,7 @@ public abstract class UUIDBased implements HasUUID, Serializable {
         this.id = id;
     }
 
+    @ApiModelProperty(position = 1, required = true, value = "string", example = "784f394c-42b6-435a-983c-b7beff2784f9")
     public UUID getId() {
         return id;
     }

common/data/src/main/java/org/thingsboard/server/common/data/security/DeviceCredentials.java

@@ -15,16 +15,18 @@
  */
 package org.thingsboard.server.common.data.security;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.EqualsAndHashCode;
 import org.thingsboard.server.common.data.BaseData;
 import org.thingsboard.server.common.data.id.DeviceCredentialsId;
 import org.thingsboard.server.common.data.id.DeviceId;
 
 @EqualsAndHashCode(callSuper = true)
+@ApiModel
 public class DeviceCredentials extends BaseData<DeviceCredentialsId> implements DeviceCredentialsFilter {
 
     private static final long serialVersionUID = -7869261127032877765L;
-    
     private DeviceId deviceId;
     private DeviceCredentialsType credentialsType;
     private String credentialsId;
@@ -46,6 +48,19 @@ public class DeviceCredentials extends BaseData<DeviceCredentialsId> implements
         this.credentialsValue = deviceCredentials.getCredentialsValue();
     }
 
+    @ApiModelProperty(position = 1, required = true, value = "string", example = "784f394c-42b6-435a-983c-b7beff2784f9")
+    @Override
+    public DeviceCredentialsId getId() {
+        return super.getId();
+    }
+
+    @ApiModelProperty(position = 2, value = "long", example = "1609459200000")
+    @Override
+    public long getCreatedTime() {
+        return super.getCreatedTime();
+    }
+
+    @ApiModelProperty(position = 3, required = true)
     public DeviceId getDeviceId() {
         return deviceId;
     }
@@ -54,6 +69,7 @@ public class DeviceCredentials extends BaseData<DeviceCredentialsId> implements
         this.deviceId = deviceId;
     }
 
+    @ApiModelProperty(position = 4, value = "string", allowableValues="ACCESS_TOKEN, X509_CERTIFICATE, MQTT_BASIC, LWM2M_CREDENTIALS")
     @Override
     public DeviceCredentialsType getCredentialsType() {
         return credentialsType;
@@ -63,6 +79,7 @@ public class DeviceCredentials extends BaseData<DeviceCredentialsId> implements
         this.credentialsType = credentialsType;
     }
 
+    @ApiModelProperty(position = 5, required = true, value = "string", example = "By default, new access token for your device. Depends on the credentialsType.")
     @Override
     public String getCredentialsId() {
         return credentialsId;
@@ -72,6 +89,7 @@ public class DeviceCredentials extends BaseData<DeviceCredentialsId> implements
         this.credentialsId = credentialsId;
     }
 
+    @ApiModelProperty(position = 6, required = false, value = "string", example = "Null in case of ACCESS_TOKEN, Depends on the credentialsType.")
     public String getCredentialsValue() {
         return credentialsValue;
     }

pom.xml

@@ -85,6 +85,7 @@
         <jar-plugin.version>3.0.2</jar-plugin.version>
         <springfox-swagger.version>2.6.1</springfox-swagger.version>
         <springfox-swagger-ui-rfc6570.version>1.0.0</springfox-swagger-ui-rfc6570.version>
+        <swagger-annotations.version>1.5.10</swagger-annotations.version>
         <spatial4j.version>0.7</spatial4j.version>
         <jts.version>1.15.0</jts.version>
         <bouncycastle.version>1.67</bouncycastle.version>
@@ -1623,6 +1624,11 @@
                 <artifactId>springfox-swagger2</artifactId>
                 <version>${springfox-swagger.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.swagger</groupId>
+                <artifactId>swagger-annotations</artifactId>
+                <version>${swagger-annotations.version}</version>
+            </dependency>
             <dependency>
                 <groupId>org.bouncycastle</groupId>
                 <artifactId>bcprov-jdk15on</artifactId>