feat(): 登录服务接口规范

src/main/java/com/muyu/auth/controller/TokenController.java

@@ -1,15 +1,19 @@
 package com.muyu.auth.controller;
 
-import com.muyu.auth.form.LoginBody;
+import com.muyu.auth.domain.LoginUserReq;
-import com.muyu.auth.form.RegisterBody;
+import com.muyu.auth.domain.RegisterUserReq;
+import com.muyu.auth.domain.TokenResp;
 import com.muyu.auth.service.SysLoginService;
 import com.muyu.common.core.domain.Result;
+import com.muyu.common.core.text.Convert;
 import com.muyu.common.core.utils.JwtUtils;
 import com.muyu.common.core.utils.StringUtils;
 import com.muyu.common.security.auth.AuthUtil;
 import com.muyu.common.security.service.TokenService;
 import com.muyu.common.security.utils.SecurityUtils;
 import com.muyu.common.system.domain.LoginUser;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -18,12 +22,15 @@ import org.springframework.web.bind.annotation.RestController;
 
 import jakarta.servlet.http.HttpServletRequest;
 
+import java.util.Map;
+
 /**
  * token 控制
  *
  * @author muyu
  */
 @RestController
+@Tag(name = "鉴权接口", description = "鉴权相关控制层")
 public class TokenController {
     @Autowired
     private TokenService tokenService;
@@ -32,14 +39,22 @@ public class TokenController {
     private SysLoginService sysLoginService;
 
     @PostMapping("login")
-    public Result<?> login (@RequestBody LoginBody form) {
+    @Operation(summary = "登录接口", description = "登录鉴权接口")
+    public Result<TokenResp> login (@RequestBody LoginUserReq form) {
         // 用户登录
         LoginUser userInfo = sysLoginService.login(form.getUsername(), form.getPassword());
         // 获取登录token
-        return Result.success(tokenService.createToken(userInfo));
+        Map<String, Object> tokenMap = tokenService.createToken(userInfo);
+        return Result.success(
+                TokenResp.builder()
+                        .accessToken(Convert.toStr(tokenMap.get("access_token")))
+                        .expiresIn(Convert.toLong(tokenMap.get("expires_in")))
+                        .build()
+        );
     }
 
     @DeleteMapping("logout")
+    @Operation(summary = "注销接口", description = "用户注销接口")
     public Result<?> logout (HttpServletRequest request) {
         String token = SecurityUtils.getToken(request);
         if (StringUtils.isNotEmpty(token)) {
@@ -53,6 +68,7 @@ public class TokenController {
     }
 
     @PostMapping("refresh")
+    @Operation(summary = "用户登录时间刷新", description = "用户登录时间刷新接口，可以进行用户token续约")
     public Result<?> refresh (HttpServletRequest request) {
         LoginUser loginUser = tokenService.getLoginUser(request);
         if (StringUtils.isNotNull(loginUser)) {
@@ -64,7 +80,7 @@ public class TokenController {
     }
 
     @PostMapping("register")
-    public Result<?> register (@RequestBody RegisterBody registerBody) {
+    public Result<?> register (@RequestBody RegisterUserReq registerBody) {
         // 用户注册
         sysLoginService.register(registerBody.getUsername(), registerBody.getPassword());
         return Result.success();

src/main/java/com/muyu/auth/domain/LoginUserReq.java

@@ -0,0 +1,39 @@
+package com.muyu.auth.domain;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.*;
+
+/**
+ * 用户登录对象
+ *
+ * @author muyu
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Tag(name = "登录请求实体类")
+public class LoginUserReq {
+    /**
+     * 用户名
+     */
+    @Schema(
+            title = "用户名称",
+            type = "String",
+            defaultValue = "admin",
+            description = "登录用户名称"
+    )
+    private String username;
+
+    /**
+     * 用户密码
+     */
+    @Schema(
+            title = "用户密码",
+            type = "String",
+            defaultValue = "admin123",
+            description = "登录用户密码"
+    )
+    private String password;
+}

src/main/java/com/muyu/auth/domain/RegisterUserReq.java

@@ -0,0 +1,10 @@
+package com.muyu.auth.domain;
+
+/**
+ * 用户注册对象
+ *
+ * @author muyu
+ */
+public class RegisterUserReq extends LoginUserReq {
+
+}

src/main/java/com/muyu/auth/domain/TokenResp.java

@@ -0,0 +1,44 @@
+package com.muyu.auth.domain;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * @Author: DongZeLiang
+ * @date: 2024/8/5
+ * @Description: token响应实体类
+ * @Version: 1.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Tag(name = "token响应结果集", description = "包含token和token有效时间")
+public class TokenResp {
+
+    /**
+     * token令牌
+     */
+    @Schema(
+            title = "token令牌",
+            type = "String",
+            defaultValue = "eyJ0e.eyJ1dlLTJJVSJ9.Pk5KS_Uh2n",
+            description = "JWT令牌，包含头，载体，尾"
+    )
+    private String accessToken;
+
+    /**
+     * 有效时间
+     */
+    @Schema(
+            title = "令牌有效时间",
+            type = "Long",
+            defaultValue = "720",
+            description = "过期时间，时间单位为分钟（MIN）"
+    )
+    private Long expiresIn;
+}

src/main/java/com/muyu/auth/form/LoginBody.java

@@ -1,34 +0,0 @@
-package com.muyu.auth.form;
-
-/**
- * 用户登录对象
- *
- * @author muyu
- */
-public class LoginBody {
-    /**
-     * 用户名
-     */
-    private String username;
-
-    /**
-     * 用户密码
-     */
-    private String password;
-
-    public String getUsername () {
-        return username;
-    }
-
-    public void setUsername (String username) {
-        this.username = username;
-    }
-
-    public String getPassword () {
-        return password;
-    }
-
-    public void setPassword (String password) {
-        this.password = password;
-    }
-}

src/main/java/com/muyu/auth/form/RegisterBody.java

@@ -1,10 +0,0 @@
-package com.muyu.auth.form;
-
-/**
- * 用户注册对象
- *
- * @author muyu
- */
-public class RegisterBody extends LoginBody {
-
-}