docs: 完善系统管理模块相关接口文档信息

continew-org · Aug 14, 2023 · ad7d699 · ad7d699
1 parent 0effc08
commit ad7d699
Show file tree

Hide file tree

Showing 27 changed files with 167 additions and 156 deletions.
diff --git a/...ew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/query/OnlineUserQuery.java b/...ew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/query/OnlineUserQuery.java
@@ -43,13 +43,13 @@ public class OnlineUserQuery implements Serializable {
     /**
      * 用户昵称
      */
-    @Schema(description = "用户昵称")
+    @Schema(description = "用户昵称", example = "张三")
     private String nickname;
 
     /**
      * 登录时间
      */
-    @Schema(description = "登录时间")
+    @Schema(description = "登录时间", example = "2023-08-08 00:00:00,2023-08-08 23:59:59")
     @DateTimeFormat(pattern = DatePattern.NORM_DATETIME_PATTERN)
     private List<Date> loginTime;
 }
diff --git a/...new-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/request/LoginRequest.java b/...new-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/request/LoginRequest.java
@@ -39,28 +39,29 @@ public class LoginRequest implements Serializable {
     /**
      * 用户名
      */
-    @Schema(description = "用户名")
+    @Schema(description = "用户名", example = "zhangsan")
     @NotBlank(message = "用户名不能为空")
     private String username;
 
     /**
      * 密码（加密）
      */
-    @Schema(description = "密码（加密）")
+    @Schema(description = "密码（加密）",
+        example = "HHwZoiBwCfh0xLdWOAd0bHOkEZlIMMOQKJyeFUw9T3ArrhL57od2i42s1o0sSXKkeHPJXvQsninhPFH2lArDDQ==")
     @NotBlank(message = "密码不能为空")
     private String password;
 
     /**
      * 验证码
      */
-    @Schema(description = "验证码")
+    @Schema(description = "验证码", example = "ABCD")
     @NotBlank(message = "验证码不能为空")
     private String captcha;
 
     /**
      * 验证码标识
      */
-    @Schema(description = "验证码标识")
+    @Schema(description = "验证码标识", example = "8a5a0296acd141a8b1bd789da867bc1a")
     @NotBlank(message = "验证码标识不能为空")
     private String uuid;
 }
diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/LoginVO.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/LoginVO.java
@@ -39,6 +39,7 @@ public class LoginVO implements Serializable {
     /**
      * 令牌
      */
-    @Schema(description = "令牌")
+    @Schema(description = "令牌",
+        example = "eyJ0eXAiOiJlV1QiLCJhbGciqiJIUzI1NiJ9.eyJsb2dpblR5cGUiOiJsb29pbiIsImxvZ2luSWQiOjEsInJuU3RyIjoiSjd4SUljYnU5cmNwU09vQ3Uyc1ND1BYYTYycFRjcjAifQ.KUPOYm-2wfuLUSfEEAbpGE527fzmkAJG7sMNcQ0pUZ8")
     private String token;
 }
diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/MetaVO.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/MetaVO.java
@@ -37,30 +37,30 @@ public class MetaVO implements Serializable {
     /**
      * 菜单标题
      */
-    @Schema(description = "菜单标题")
+    @Schema(description = "菜单标题", example = "用户管理")
     private String locale;
 
     /**
      * 菜单图标
      */
-    @Schema(description = "菜单图标")
+    @Schema(description = "菜单图标", example = "user")
     private String icon;
 
     /**
      * 是否隐藏
      */
-    @Schema(description = "是否隐藏")
+    @Schema(description = "是否隐藏", example = "false")
     private Boolean hideInMenu;
 
     /**
      * 是否缓存
      */
-    @Schema(description = "是否缓存")
+    @Schema(description = "是否缓存", example = "false")
     private Boolean ignoreCache;
 
     /**
      * 是否需要登录才能访问
      */
-    @Schema(description = "是否需要登录才能访问")
+    @Schema(description = "是否需要登录才能访问", example = "false")
     private Boolean requiresAuth = true;
 }
diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/OnlineUserVO.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/OnlineUserVO.java
@@ -38,48 +38,49 @@ public class OnlineUserVO implements Serializable {
     /**
      * ID
      */
-    @Schema(description = "ID")
+    @Schema(description = "ID", example = "1")
     private Long id;
 
     /**
      * 令牌
      */
-    @Schema(description = "令牌")
+    @Schema(description = "令牌",
+        example = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpblR5cGUiOiJsb2dpbiIsImxvZ2luSWQiOjEsInJuU3RyIjoiTUd6djdyOVFoeHEwdVFqdFAzV3M5YjVJRzh4YjZPSEUifQ.7q7U3ouoN7WPhH2kUEM7vPe5KF3G_qavSG-vRgIxKvE")
     private String token;
 
     /**
      * 用户名
      */
-    @Schema(description = "用户名")
+    @Schema(description = "用户名", example = "zhangsan")
     private String username;
 
     /**
      * 昵称
      */
-    @Schema(description = "昵称")
+    @Schema(description = "昵称", example = "张三")
     private String nickname;
 
     /**
      * 登录 IP
      */
-    @Schema(description = "登录 IP")
+    @Schema(description = "登录 IP", example = "192.168.0.1")
     private String clientIp;
 
     /**
      * 登录地点
      */
-    @Schema(description = "登录地点")
+    @Schema(description = "登录地点", example = "中国北京北京市")
     private String location;
 
     /**
      * 浏览器
      */
-    @Schema(description = "浏览器")
+    @Schema(description = "浏览器", example = "Chrome 115.0.0.0")
     private String browser;
 
     /**
      * 登录时间
      */
-    @Schema(description = "登录时间")
+    @Schema(description = "登录时间", example = "2023-08-08 08:08:08")
     private LocalDateTime loginTime;
 }
diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/RouteVO.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/RouteVO.java
@@ -41,19 +41,19 @@ public class RouteVO implements Serializable {
     /**
      * 路由地址
      */
-    @Schema(description = "路由地址")
+    @Schema(description = "路由地址", example = "/system/user")
     private String path;
 
     /**
      * 组件名称
      */
-    @Schema(description = "组件名称")
+    @Schema(description = "组件名称", example = "User")
     private String name;
 
     /**
      * 组件路径
      */
-    @Schema(description = "组件路径")
+    @Schema(description = "组件路径", example = "/system/user/index")
     private String component;
 
     /**

diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/UserInfoVO.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/auth/model/vo/UserInfoVO.java
@@ -46,91 +46,93 @@ public class UserInfoVO implements Serializable {
     /**
      * ID
      */
-    @Schema(description = "ID")
+    @Schema(description = "ID", example = "1")
     private Long id;
 
     /**
      * 用户名
      */
-    @Schema(description = "用户名")
+    @Schema(description = "用户名", example = "zhangsan")
     private String username;
 
     /**
      * 昵称
      */
-    @Schema(description = "昵称")
+    @Schema(description = "昵称", example = "张三")
     private String nickname;
 
     /**
      * 性别（0：未知，1：男，2：女）
      */
-    @Schema(description = "性别（0：未知，1：男，2：女）", type = "Integer", allowableValues = {"0", "1", "2"})
+    @Schema(description = "性别（0：未知，1：男，2：女）", type = "Integer", allowableValues = {"0", "1", "2"}, example = "1")
     private GenderEnum gender;
 
     /**
      * 邮箱
      */
-    @Schema(description = "邮箱")
+    @Schema(description = "邮箱", example = "[email protected]")
     private String email;
 
     /**
      * 手机号码
      */
-    @Schema(description = "手机号码")
+    @Schema(description = "手机号码", example = "13811111111")
     private String phone;
 
     /**
      * 头像地址
      */
-    @Schema(description = "头像地址")
+    @Schema(description = "头像地址",
+        example = "https://himg.bdimg.com/sys/portrait/item/public.1.81ac9a9e.rf1ix17UfughLQjNo7XQ_w.jpg")
     private String avatar;
 
     /**
      * 描述
      */
-    @Schema(description = "描述")
+    @Schema(description = "描述", example = "张三用户")
     private String description;
 
     /**
      * 最后一次修改密码时间
      */
-    @Schema(description = "最后一次修改密码时间")
+    @Schema(description = "最后一次修改密码时间", example = "2023-08-08 08:08:08")
     private LocalDateTime pwdResetTime;
 
     /**
      * 创建时间
      */
+    @Schema(description = "创建时间", example = "2023-08-08 08:08:08")
     @JsonIgnore
     private LocalDateTime createTime;
 
     /**
      * 注册日期
      */
-    @Schema(description = "注册日期")
+    @Schema(description = "注册日期", example = "2023-08-08")
     private LocalDate registrationDate;
 
     /**
      * 部门 ID
      */
-    @Schema(description = "部门 ID")
+    @Schema(description = "部门 ID", example = "1")
     private Long deptId;
 
     /**
      * 所属部门
      */
-    @Schema(description = "所属名称")
+    @Schema(description = "所属部门", example = "测试部")
     private String deptName;
 
     /**
      * 权限码集合
      */
-    @Schema(description = "权限码集合")
+    @Schema(description = "权限码集合", example = "[system:user:list,system:user:add]")
     private Set<String> permissions;
 
     /**
      * 角色编码集合
      */
-    @Schema(description = "角色编码集合")
+    @Schema(description = "角色编码集合", example = "[admin,test]")
     private Set<String> roles;
 
     public String getPhone() {

diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/DeptQuery.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/DeptQuery.java
@@ -40,14 +40,14 @@ public class DeptQuery implements Serializable {
     /**
      * 部门名称
      */
-    @Schema(description = "部门名称")
+    @Schema(description = "部门名称", example = "测试部")
     @Query(type = QueryTypeEnum.INNER_LIKE)
     private String name;
 
     /**
      * 状态（1：启用，2：禁用）
      */
-    @Schema(description = "状态（1：启用，2：禁用）")
+    @Schema(description = "状态（1：启用，2：禁用）", example = "1")
     @Query
     private Integer status;
 }
diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/MenuQuery.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/MenuQuery.java
@@ -40,14 +40,14 @@ public class MenuQuery implements Serializable {
     /**
      * 菜单标题
      */
-    @Schema(description = "菜单标题")
+    @Schema(description = "菜单标题", example = "用户管理")
     @Query(type = QueryTypeEnum.INNER_LIKE)
     private String title;
 
     /**
      * 状态（1：启用，2：禁用）
      */
-    @Schema(description = "状态（1：启用，2：禁用）")
+    @Schema(description = "状态（1：启用，2：禁用）", example = "1")
     @Query
     private Integer status;
 }
diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/RoleQuery.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/RoleQuery.java
@@ -39,14 +39,14 @@ public class RoleQuery implements Serializable {
     /**
      * 角色名称
      */
-    @Schema(description = "角色名称")
+    @Schema(description = "角色名称", example = "测试人员")
     @Query(blurry = "name,code")
     private String name;
 
     /**
      * 状态（1：启用，2：禁用）
      */
-    @Schema(description = "状态（1：启用，2：禁用）")
+    @Schema(description = "状态（1：启用，2：禁用）", example = "1")
     @Query
     private Integer status;
 }
diff --git a/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/UserQuery.java b/continew-admin-system/src/main/java/top/charles7c/cnadmin/system/model/query/UserQuery.java
@@ -46,29 +46,29 @@ public class UserQuery implements Serializable {
     /**
      * 用户名
      */
-    @Schema(description = "用户名")
+    @Schema(description = "用户名", example = "zhangsan")
     @Query(blurry = "username,nickname,email,phone")
     private String username;
 
     /**
      * 状态（1：启用，2：禁用）
      */
-    @Schema(description = "状态（1：启用，2：禁用）")
+    @Schema(description = "状态（1：启用，2：禁用）", example = "1")
     @Query
     private Integer status;
 
     /**
      * 创建时间
      */
-    @Schema(description = "创建时间")
+    @Schema(description = "创建时间", example = "2023-08-08 00:00:00,2023-08-08 23:59:59")
     @Query(type = QueryTypeEnum.BETWEEN)
     @DateTimeFormat(pattern = DatePattern.NORM_DATETIME_PATTERN)
     private List<Date> createTime;
 
     /**
      * 部门 ID
      */
-    @Schema(description = "部门 ID")
+    @Schema(description = "部门 ID", example = "1")
     @Query
     private Long deptId;
 }