Swagger docs for TwoFactorAuthController

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

@@ -15,6 +15,8 @@
  */
 package org.thingsboard.server.controller;
 
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -35,9 +37,8 @@ import org.thingsboard.server.service.security.system.SystemSecurityService;
 
 import javax.servlet.http.HttpServletRequest;
 
-/*
- * FIXME [viacheslav]: Swagger documentation
- * */
+import static org.thingsboard.server.controller.ControllerConstants.NEW_LINE;
+
 @RestController
 @RequestMapping("/api/auth/2fa")
 @TbCoreComponent
@@ -50,16 +51,30 @@ public class TwoFactorAuthController extends BaseController {
     private final UserService userService;
 
 
+    @ApiOperation(value = "Request 2FA verification code (requestTwoFaVerificationCode)",
+            notes = "Request 2FA verification code." + NEW_LINE +
+                    "To make a request to this endpoint, you need an access token with the scope of PRE_VERIFICATION_TOKEN, " +
+                    "which is issued on username/password auth if 2FA is enabled." + NEW_LINE +
+                    "The API method is rate limited (using rate limit config from TwoFactorAuthSettings). " +
+                    "Will return a Bad Request error if provider is not configured for usage, " +
+                    "and Too Many Requests error if rate limits are exceeded.")
     @PostMapping("/verification/send")
     @PreAuthorize("hasAuthority('PRE_VERIFICATION_TOKEN')")
-    public void sendTwoFaVerificationCode() throws Exception {
+    public void requestTwoFaVerificationCode() throws Exception {
         SecurityUser user = getCurrentUser();
         twoFactorAuthService.prepareVerificationCode(user, true);
     }
 
+    @ApiOperation(value = "Check 2FA verification code (checkTwoFaVerificationCode)",
+            notes = "Checks 2FA verification code, and if it is correct the method returns a regular access and refresh token pair." + NEW_LINE +
+                    "The API method is rate limited (using rate limit config from TwoFactorAuthSettings), and also will block a user " +
+                    "after X unsuccessful verification attempts if such behavior is configured (in TwoFactorAuthSettings)." + NEW_LINE +
+                    "Will return a Bad Request error if provider is not configured for usage, " +
+                    "and Too Many Requests error if rate limits are exceeded.")
     @PostMapping("/verification/check")
     @PreAuthorize("hasAuthority('PRE_VERIFICATION_TOKEN')")
-    public JwtTokenPair checkTwoFaVerificationCode(@RequestParam String verificationCode, HttpServletRequest servletRequest) throws Exception {
+    public JwtTokenPair checkTwoFaVerificationCode(@ApiParam(value = "6-digit verification code", required = true)
+                                                   @RequestParam String verificationCode, HttpServletRequest servletRequest) throws Exception {
         SecurityUser user = getCurrentUser();
         boolean verificationSuccess = twoFactorAuthService.checkVerificationCode(user, verificationCode, true);
         if (verificationSuccess) {