简柏林 / thingskit · Commits

Commit e6e05c9b885f3f18a0556e3a5e6804bb74372667

Authored by Andrii Shvaika
1 parent bf56d9e1

Admin Controller description

Inline Side-by-side
Showing 8 changed files with 96 additions and 7 deletions
@@ -16,6 +16,8 @@ @@ -16,6 +16,8 @@
16 package org.thingsboard.server.controller; 16 package org.thingsboard.server.controller;
17 17
18 import com.fasterxml.jackson.databind.node.ObjectNode; 18 import com.fasterxml.jackson.databind.node.ObjectNode;
  19 +import io.swagger.annotations.ApiOperation;
  20 +import io.swagger.annotations.ApiParam;
19 import org.springframework.beans.factory.annotation.Autowired; 21 import org.springframework.beans.factory.annotation.Autowired;
20 import org.springframework.security.access.prepost.PreAuthorize; 22 import org.springframework.security.access.prepost.PreAuthorize;
21 import org.springframework.web.bind.annotation.PathVariable; 23 import org.springframework.web.bind.annotation.PathVariable;
@@ -44,6 +46,7 @@ import org.thingsboard.server.service.update.UpdateService; @@ -44,6 +46,7 @@ import org.thingsboard.server.service.update.UpdateService;
44 @RequestMapping("/api/admin") 46 @RequestMapping("/api/admin")
45 public class AdminController extends BaseController { 47 public class AdminController extends BaseController {
46 48
  49 + public static final String SYS_ADMIN_AUTHORITY_ONLY = " Available for users with System Administrator ('SYS_ADMIN') authority only.";
47 @Autowired 50 @Autowired
48 private MailService mailService; 51 private MailService mailService;
49 52
@@ -59,10 +62,14 @@ public class AdminController extends BaseController { @@ -59,10 +62,14 @@ public class AdminController extends BaseController {
59 @Autowired 62 @Autowired
60 private UpdateService updateService; 63 private UpdateService updateService;
61 64
  65 + @ApiOperation(value = "Get the Administration Settings object using key (getAdminSettings)",
  66 + notes = "Get the Administration Settings object using specified string key. Referencing non-existing key will cause an error." + SYS_ADMIN_AUTHORITY_ONLY)
62 @PreAuthorize("hasAuthority('SYS_ADMIN')") 67 @PreAuthorize("hasAuthority('SYS_ADMIN')")
63 @RequestMapping(value = "/settings/{key}", method = RequestMethod.GET) 68 @RequestMapping(value = "/settings/{key}", method = RequestMethod.GET)
64 @ResponseBody 69 @ResponseBody
65 - public AdminSettings getAdminSettings(@PathVariable("key") String key) throws ThingsboardException { 70 + public AdminSettings getAdminSettings(
  71 + @ApiParam(value = "A string value of the key (e.g. 'general' or 'mail').")
  72 + @PathVariable("key") String key) throws ThingsboardException {
66 try { 73 try {
67 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.READ); 74 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.READ);
68 AdminSettings adminSettings = checkNotNull(adminSettingsService.findAdminSettingsByKey(TenantId.SYS_TENANT_ID, key)); 75 AdminSettings adminSettings = checkNotNull(adminSettingsService.findAdminSettingsByKey(TenantId.SYS_TENANT_ID, key));
@@ -75,10 +82,17 @@ public class AdminController extends BaseController { @@ -75,10 +82,17 @@ public class AdminController extends BaseController {
75 } 82 }
76 } 83 }
77 84
  85 +
  86 + @ApiOperation(value = "Get the Administration Settings object using key (getAdminSettings)",
  87 + notes = "Creates or Updates the Administration Settings. Platform generates random Administration Settings Id during settings creation. " +
  88 + "The Administration Settings Id will be present in the response. Specify the Administration Settings Id when you would like to update the Administration Settings. " +
  89 + "Referencing non-existing Administration Settings Id will cause an error." + SYS_ADMIN_AUTHORITY_ONLY)
78 @PreAuthorize("hasAuthority('SYS_ADMIN')") 90 @PreAuthorize("hasAuthority('SYS_ADMIN')")
79 @RequestMapping(value = "/settings", method = RequestMethod.POST) 91 @RequestMapping(value = "/settings", method = RequestMethod.POST)
80 @ResponseBody 92 @ResponseBody
81 - public AdminSettings saveAdminSettings(@RequestBody AdminSettings adminSettings) throws ThingsboardException { 93 + public AdminSettings saveAdminSettings(
  94 + @ApiParam(value = "A JSON value representing the Administration Settings.")
  95 + @RequestBody AdminSettings adminSettings) throws ThingsboardException {
82 try { 96 try {
83 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.WRITE); 97 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.WRITE);
84 adminSettings = checkNotNull(adminSettingsService.saveAdminSettings(TenantId.SYS_TENANT_ID, adminSettings)); 98 adminSettings = checkNotNull(adminSettingsService.saveAdminSettings(TenantId.SYS_TENANT_ID, adminSettings));
@@ -94,6 +108,8 @@ public class AdminController extends BaseController { @@ -94,6 +108,8 @@ public class AdminController extends BaseController {
94 } 108 }
95 } 109 }
96 110
  111 + @ApiOperation(value = "Get the Security Settings object",
  112 + notes = "Get the Security Settings object that contains password policy, etc." + SYS_ADMIN_AUTHORITY_ONLY)
97 @PreAuthorize("hasAuthority('SYS_ADMIN')") 113 @PreAuthorize("hasAuthority('SYS_ADMIN')")
98 @RequestMapping(value = "/securitySettings", method = RequestMethod.GET) 114 @RequestMapping(value = "/securitySettings", method = RequestMethod.GET)
99 @ResponseBody 115 @ResponseBody
@@ -106,10 +122,14 @@ public class AdminController extends BaseController { @@ -106,10 +122,14 @@ public class AdminController extends BaseController {
106 } 122 }
107 } 123 }
108 124
  125 + @ApiOperation(value = "Update Security Settings (saveSecuritySettings)",
  126 + notes = "Updates the Security Settings object that contains password policy, etc." + SYS_ADMIN_AUTHORITY_ONLY)
109 @PreAuthorize("hasAuthority('SYS_ADMIN')") 127 @PreAuthorize("hasAuthority('SYS_ADMIN')")
110 @RequestMapping(value = "/securitySettings", method = RequestMethod.POST) 128 @RequestMapping(value = "/securitySettings", method = RequestMethod.POST)
111 @ResponseBody 129 @ResponseBody
112 - public SecuritySettings saveSecuritySettings(@RequestBody SecuritySettings securitySettings) throws ThingsboardException { 130 + public SecuritySettings saveSecuritySettings(
  131 + @ApiParam(value = "A JSON value representing the Security Settings.")
  132 + @RequestBody SecuritySettings securitySettings) throws ThingsboardException {
113 try { 133 try {
114 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.WRITE); 134 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.WRITE);
115 securitySettings = checkNotNull(systemSecurityService.saveSecuritySettings(TenantId.SYS_TENANT_ID, securitySettings)); 135 securitySettings = checkNotNull(systemSecurityService.saveSecuritySettings(TenantId.SYS_TENANT_ID, securitySettings));
@@ -119,14 +139,19 @@ public class AdminController extends BaseController { @@ -119,14 +139,19 @@ public class AdminController extends BaseController {
119 } 139 }
120 } 140 }
121 141
  142 + @ApiOperation(value = "Send test email (sendTestMail)",
  143 + notes = "Attempts to send test email to the System Administrator User using Mail Settings provided as a parameter. " +
  144 + "You may change the 'To' email in the user profile of the System Administrator. " + SYS_ADMIN_AUTHORITY_ONLY)
122 @PreAuthorize("hasAuthority('SYS_ADMIN')") 145 @PreAuthorize("hasAuthority('SYS_ADMIN')")
123 @RequestMapping(value = "/settings/testMail", method = RequestMethod.POST) 146 @RequestMapping(value = "/settings/testMail", method = RequestMethod.POST)
124 - public void sendTestMail(@RequestBody AdminSettings adminSettings) throws ThingsboardException { 147 + public void sendTestMail(
  148 + @ApiParam(value = "A JSON value representing the Mail Settings.")
  149 + @RequestBody AdminSettings adminSettings) throws ThingsboardException {
125 try { 150 try {
126 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.READ); 151 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.READ);
127 adminSettings = checkNotNull(adminSettings); 152 adminSettings = checkNotNull(adminSettings);
128 if (adminSettings.getKey().equals("mail")) { 153 if (adminSettings.getKey().equals("mail")) {
129 - if(!adminSettings.getJsonValue().has("password")) { 154 + if (!adminSettings.getJsonValue().has("password")) {
130 AdminSettings mailSettings = checkNotNull(adminSettingsService.findAdminSettingsByKey(TenantId.SYS_TENANT_ID, "mail")); 155 AdminSettings mailSettings = checkNotNull(adminSettingsService.findAdminSettingsByKey(TenantId.SYS_TENANT_ID, "mail"));
131 ((ObjectNode) adminSettings.getJsonValue()).put("password", mailSettings.getJsonValue().get("password").asText()); 156 ((ObjectNode) adminSettings.getJsonValue()).put("password", mailSettings.getJsonValue().get("password").asText());
132 } 157 }
@@ -138,9 +163,14 @@ public class AdminController extends BaseController { @@ -138,9 +163,14 @@ public class AdminController extends BaseController {
138 } 163 }
139 } 164 }
140 165
  166 + @ApiOperation(value = "Send test sms (sendTestMail)",
  167 + notes = "Attempts to send test sms to the System Administrator User using SMS Settings and phone number provided as a parameters of the request. "
  168 + + SYS_ADMIN_AUTHORITY_ONLY)
141 @PreAuthorize("hasAuthority('SYS_ADMIN')") 169 @PreAuthorize("hasAuthority('SYS_ADMIN')")
142 @RequestMapping(value = "/settings/testSms", method = RequestMethod.POST) 170 @RequestMapping(value = "/settings/testSms", method = RequestMethod.POST)
143 - public void sendTestSms(@RequestBody TestSmsRequest testSmsRequest) throws ThingsboardException { 171 + public void sendTestSms(
  172 + @ApiParam(value = "A JSON value representing the Test SMS request.")
  173 + @RequestBody TestSmsRequest testSmsRequest) throws ThingsboardException {
144 try { 174 try {
145 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.READ); 175 accessControlService.checkPermission(getCurrentUser(), Resource.ADMIN_SETTINGS, Operation.READ);
146 smsService.sendTestSms(testSmsRequest); 176 smsService.sendTestSms(testSmsRequest);
@@ -149,6 +179,9 @@ public class AdminController extends BaseController { @@ -149,6 +179,9 @@ public class AdminController extends BaseController {
149 } 179 }
150 } 180 }
151 181
  182 + @ApiOperation(value = "Check for new Platform Releases (checkUpdates)",
  183 + notes = "Check notifications about new platform releases. "
  184 + + SYS_ADMIN_AUTHORITY_ONLY)
152 @PreAuthorize("hasAuthority('SYS_ADMIN')") 185 @PreAuthorize("hasAuthority('SYS_ADMIN')")
153 @RequestMapping(value = "/updates", method = RequestMethod.GET) 186 @RequestMapping(value = "/updates", method = RequestMethod.GET)
154 @ResponseBody 187 @ResponseBody
@@ -15,11 +15,15 @@ @@ -15,11 +15,15 @@
15 */ 15 */
16 package org.thingsboard.server.common.data; 16 package org.thingsboard.server.common.data;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import org.thingsboard.server.common.data.id.AdminSettingsId; 20 import org.thingsboard.server.common.data.id.AdminSettingsId;
19 21
20 import com.fasterxml.jackson.databind.JsonNode; 22 import com.fasterxml.jackson.databind.JsonNode;
  23 +import org.thingsboard.server.common.data.id.DeviceId;
21 import org.thingsboard.server.common.data.validation.NoXss; 24 import org.thingsboard.server.common.data.validation.NoXss;
22 25
  26 +@ApiModel
23 public class AdminSettings extends BaseData<AdminSettingsId> { 27 public class AdminSettings extends BaseData<AdminSettingsId> {
24 28
25 private static final long serialVersionUID = -7670322981725511892L; 29 private static final long serialVersionUID = -7670322981725511892L;
@@ -42,6 +46,19 @@ public class AdminSettings extends BaseData<AdminSettingsId> { @@ -42,6 +46,19 @@ public class AdminSettings extends BaseData<AdminSettingsId> {
42 this.jsonValue = adminSettings.getJsonValue(); 46 this.jsonValue = adminSettings.getJsonValue();
43 } 47 }
44 48
  49 + @ApiModelProperty(position = 1, value = "The Id of the Administration Settings, auto-generated, UUID")
  50 + @Override
  51 + public AdminSettingsId getId() {
  52 + return super.getId();
  53 + }
  54 +
  55 + @ApiModelProperty(position = 2, value = "Timestamp of the settings creation, in milliseconds", example = "1609459200000", readOnly = true)
  56 + @Override
  57 + public long getCreatedTime() {
  58 + return super.getCreatedTime();
  59 + }
  60 +
  61 + @ApiModelProperty(position = 3, value = "The Administration Settings key, (e.g. 'general' or 'mail')")
45 public String getKey() { 62 public String getKey() {
46 return key; 63 return key;
47 } 64 }
@@ -50,6 +67,7 @@ public class AdminSettings extends BaseData<AdminSettingsId> { @@ -50,6 +67,7 @@ public class AdminSettings extends BaseData<AdminSettingsId> {
50 this.key = key; 67 this.key = key;
51 } 68 }
52 69
  70 + @ApiModelProperty(position = 4, value = "JSON representation of the Administration Settings value")
53 public JsonNode getJsonValue() { 71 public JsonNode getJsonValue() {
54 return jsonValue; 72 return jsonValue;
55 } 73 }
@@ -15,12 +15,17 @@ @@ -15,12 +15,17 @@
15 */ 15 */
16 package org.thingsboard.server.common.data; 16 package org.thingsboard.server.common.data;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.Data; 20 import lombok.Data;
19 21
  22 +@ApiModel
20 @Data 23 @Data
21 public class UpdateMessage { 24 public class UpdateMessage {
22 25
  26 + @ApiModelProperty(position = 1, value = "The message about new platform update available.")
23 private final String message; 27 private final String message;
  28 + @ApiModelProperty(position = 1, value = "'True' if new platform update is available.")
24 private final boolean isUpdateAvailable; 29 private final boolean isUpdateAvailable;
25 30
26 } 31 }
@@ -15,15 +15,20 @@ @@ -15,15 +15,20 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.security.model; 16 package org.thingsboard.server.common.data.security.model;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.Data; 20 import lombok.Data;
19 21
20 import java.io.Serializable; 22 import java.io.Serializable;
21 23
  24 +@ApiModel
22 @Data 25 @Data
23 public class SecuritySettings implements Serializable { 26 public class SecuritySettings implements Serializable {
24 27
  28 + @ApiModelProperty(position = 1, value = "The user password policy object." )
25 private UserPasswordPolicy passwordPolicy; 29 private UserPasswordPolicy passwordPolicy;
26 - 30 + @ApiModelProperty(position = 2, value = "Maximum number of failed login attempts allowed before user account is locked." )
27 private Integer maxFailedLoginAttempts; 31 private Integer maxFailedLoginAttempts;
  32 + @ApiModelProperty(position = 3, value = "Email to use for notifications about locked users." )
28 private String userLockoutNotificationEmail; 33 private String userLockoutNotificationEmail;
29 } 34 }
@@ -15,20 +15,30 @@ @@ -15,20 +15,30 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.security.model; 16 package org.thingsboard.server.common.data.security.model;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.Data; 20 import lombok.Data;
19 21
20 import java.io.Serializable; 22 import java.io.Serializable;
21 23
  24 +@ApiModel
22 @Data 25 @Data
23 public class UserPasswordPolicy implements Serializable { 26 public class UserPasswordPolicy implements Serializable {
24 27
  28 + @ApiModelProperty(position = 1, value = "Minimum number of symbols in the password." )
25 private Integer minimumLength; 29 private Integer minimumLength;
  30 + @ApiModelProperty(position = 1, value = "Minimum number of uppercase letters in the password." )
26 private Integer minimumUppercaseLetters; 31 private Integer minimumUppercaseLetters;
  32 + @ApiModelProperty(position = 1, value = "Minimum number of lowercase letters in the password." )
27 private Integer minimumLowercaseLetters; 33 private Integer minimumLowercaseLetters;
  34 + @ApiModelProperty(position = 1, value = "Minimum number of digits in the password." )
28 private Integer minimumDigits; 35 private Integer minimumDigits;
  36 + @ApiModelProperty(position = 1, value = "Minimum number of special in the password." )
29 private Integer minimumSpecialCharacters; 37 private Integer minimumSpecialCharacters;
30 38
  39 + @ApiModelProperty(position = 1, value = "Password expiration period (days). Force expiration of the password." )
31 private Integer passwordExpirationPeriodDays; 40 private Integer passwordExpirationPeriodDays;
  41 + @ApiModelProperty(position = 1, value = "Password reuse frequency (days). Disallow to use the same password for the defined number of days" )
32 private Integer passwordReuseFrequencyDays; 42 private Integer passwordReuseFrequencyDays;
33 43
34 } 44 }
@@ -15,13 +15,19 @@ @@ -15,13 +15,19 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.sms.config; 16 package org.thingsboard.server.common.data.sms.config;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.Data; 20 import lombok.Data;
19 21
  22 +@ApiModel
20 @Data 23 @Data
21 public class AwsSnsSmsProviderConfiguration implements SmsProviderConfiguration { 24 public class AwsSnsSmsProviderConfiguration implements SmsProviderConfiguration {
22 25
  26 + @ApiModelProperty(position = 1, value = "The AWS SNS Access Key ID.")
23 private String accessKeyId; 27 private String accessKeyId;
  28 + @ApiModelProperty(position = 2, value = "The AWS SNS Access Key.")
24 private String secretAccessKey; 29 private String secretAccessKey;
  30 + @ApiModelProperty(position = 3, value = "The AWS region.")
25 private String region; 31 private String region;
26 32
27 @Override 33 @Override
@@ -15,13 +15,19 @@ @@ -15,13 +15,19 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.sms.config; 16 package org.thingsboard.server.common.data.sms.config;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.Data; 20 import lombok.Data;
19 21
  22 +@ApiModel
20 @Data 23 @Data
21 public class TestSmsRequest { 24 public class TestSmsRequest {
22 25
  26 + @ApiModelProperty(position = 1, value = "The SMS provider configuration")
23 private SmsProviderConfiguration providerConfiguration; 27 private SmsProviderConfiguration providerConfiguration;
  28 + @ApiModelProperty(position = 2, value = "The phone number or other identifier to specify as a recipient of the SMS.")
24 private String numberTo; 29 private String numberTo;
  30 + @ApiModelProperty(position = 3, value = "The test message")
25 private String message; 31 private String message;
26 32
27 } 33 }
@@ -15,13 +15,19 @@ @@ -15,13 +15,19 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.sms.config; 16 package org.thingsboard.server.common.data.sms.config;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.Data; 20 import lombok.Data;
19 21
  22 +@ApiModel
20 @Data 23 @Data
21 public class TwilioSmsProviderConfiguration implements SmsProviderConfiguration { 24 public class TwilioSmsProviderConfiguration implements SmsProviderConfiguration {
22 25
  26 + @ApiModelProperty(position = 1, value = "Twilio account Sid.")
23 private String accountSid; 27 private String accountSid;
  28 + @ApiModelProperty(position = 2, value = "Twilio account Token.")
24 private String accountToken; 29 private String accountToken;
  30 + @ApiModelProperty(position = 3, value = "The number/id of a sender.")
25 private String numberFrom; 31 private String numberFrom;
26 32
27 @Override 33 @Override