docs: swagger docs refacto & perf

play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayBalanceDetailsInfoController.java

@@ -6,6 +6,12 @@ import com.starry.admin.modules.personnel.service.IPlayBalanceDetailsInfoService
 import com.starry.common.annotation.Log;
 import com.starry.common.enums.BusinessType;
 import com.starry.common.result.R;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
@@ -17,6 +23,7 @@ import javax.annotation.Resource;
  * @author admin
  * @since 2024-04-30
  */
+@Api(tags = "余额明细管理", description = "余额明细信息管理相关接口，包括查询、修改和删除等操作")
 @RestController
 @RequestMapping("/balance/details")
 public class PlayBalanceDetailsInfoController {
@@ -27,14 +34,23 @@ public class PlayBalanceDetailsInfoController {
     /**
      * 查询余额明细列表
      */
+    @ApiOperation(value = "分页查询明细列表", notes = "分页查询余额明细信息列表")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功")
+    })
     @PostMapping("/listByPage")
-    public R list(@Validated @RequestBody PlayBalanceDetailsQueryVo vo) {
+    public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayBalanceDetailsQueryVo vo) {
         return R.ok(playBalanceDetailsInfoService.selectByPage(vo));
     }
 
     /**
      * 获取余额明细详细信息
      */
+    @ApiOperation(value = "获取明细详情", notes = "根据ID获取余额明细详细信息")
+    @ApiImplicitParam(name = "id", value = "明细ID", required = true, paramType = "path", dataType = "String", example = "1")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功", response = PlayBalanceDetailsInfoEntity.class)
+    })
     @GetMapping(value = "/{id}")
     public R getInfo(@PathVariable("id") String id) {
         return R.ok(playBalanceDetailsInfoService.selectPlayBalanceDetailsInfoById(id));
@@ -44,10 +60,16 @@ public class PlayBalanceDetailsInfoController {
     /**
      * 修改余额明细
      */
+    @ApiOperation(value = "修改明细信息", notes = "修改余额明细信息")
+    @ApiImplicitParam(name = "id", value = "明细ID", required = true, paramType = "path", dataType = "String", example = "1")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "修改失败，包含详细错误信息")
+    })
     //@PreAuthorize("@customSs.hasPermission('balance:details:update')")
     @Log(title = "余额明细", businessType = BusinessType.UPDATE)
     @PostMapping(value = "/update/{id}")
-    public R update(@PathVariable String id, @RequestBody PlayBalanceDetailsInfoEntity playBalanceDetailsInfo) {
+    public R update(@PathVariable String id, @ApiParam(value = "明细信息", required = true) @RequestBody PlayBalanceDetailsInfoEntity playBalanceDetailsInfo) {
         playBalanceDetailsInfo.setId(id);
         boolean success = playBalanceDetailsInfoService.update(playBalanceDetailsInfo);
         if (success) {
@@ -59,6 +81,11 @@ public class PlayBalanceDetailsInfoController {
     /**
      * 删除余额明细
      */
+    @ApiOperation(value = "删除明细信息", notes = "根据ID批量删除余额明细信息")
+    @ApiImplicitParam(name = "ids", value = "明细ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功")
+    })
     //@PreAuthorize("@customSs.hasPermission('balance:details:delete')")
     @Log(title = "余额明细", businessType = BusinessType.DELETE)
     @DeleteMapping("/{ids}")

play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelAdminInfoController.java

@@ -16,6 +16,12 @@ import com.starry.common.annotation.Log;
 import com.starry.common.enums.BusinessType;
 import com.starry.common.result.R;
 import com.starry.common.utils.ConvertUtil;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
@@ -29,6 +35,7 @@ import java.time.LocalDateTime;
  * @author admin
  * @since 2024-06-14
  */
+@Api(tags = "管理员管理", description = "管理员信息管理相关接口，包括查询、新增、修改和删除等操作")
 @RestController
 @RequestMapping("/personnel/admin")
 public class PlayPersonnelAdminInfoController {
@@ -49,8 +56,12 @@ public class PlayPersonnelAdminInfoController {
     /**
      * 查询管理员管理信息列表
      */
+    @ApiOperation(value = "分页查询管理员列表", notes = "分页查询管理员信息列表")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功", response = PlayPersonnelAdminInfoReturnVo.class, responseContainer = "Page")
+    })
     @PostMapping("/listByPage")
-    public R listByPage(@Validated @RequestBody PlayPersonnelAdminInfoQueryVo vo) {
+    public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayPersonnelAdminInfoQueryVo vo) {
         IPage<PlayPersonnelAdminInfoReturnVo> list = playPersonnelAdminInfoService.selectByPage(vo);
         return R.ok(list);
     }
@@ -59,6 +70,11 @@ public class PlayPersonnelAdminInfoController {
     /**
      * 获取管理员管理详细信息
      */
+    @ApiOperation(value = "获取管理员详情", notes = "根据ID获取管理员详细信息")
+    @ApiImplicitParam(name = "id", value = "管理员ID", required = true, paramType = "path", dataType = "String", example = "1")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功", response = PlayPersonnelAdminInfoEntity.class)
+    })
     @GetMapping(value = "/{id}")
     public R getInfo(@PathVariable("id") String id) {
         return R.ok(playPersonnelAdminInfoService.selectPlayPersonnelAdminInfoById(id));
@@ -67,9 +83,14 @@ public class PlayPersonnelAdminInfoController {
     /**
      * 新增管理员管理信息
      */
+    @ApiOperation(value = "新增管理员信息", notes = "创建新的管理员信息")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "添加失败，包含详细错误信息")
+    })
     @Log(title = "管理员管理信息", businessType = BusinessType.INSERT)
     @PostMapping("/createBaseInfo")
-    public R createBaseInfo(@Validated @RequestBody PlayPersonnelAdminInfoEditAddInfoVo vo) {
+    public R createBaseInfo(@ApiParam(value = "管理员信息", required = true) @Validated @RequestBody PlayPersonnelAdminInfoEditAddInfoVo vo) {
         //校验对应用户是否存在
         SysUserEntity sysUserEntity = sysUserService.selectUserById(vo.getSysUserId());
         //校验当前用户是否已经是组长
@@ -93,9 +114,14 @@ public class PlayPersonnelAdminInfoController {
     /**
      * 修改管理员管理信息
      */
+    @ApiOperation(value = "修改管理员信息", notes = "修改管理员基本信息")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "修改失败，包含详细错误信息")
+    })
     @Log(title = "管理员管理信息", businessType = BusinessType.UPDATE)
     @PostMapping(value = "/updateBaseInfo")
-    public R updateBaseInfo(@Validated @RequestBody PlayPersonnelAdminInfoEditBaseInfoVo vo) {
+    public R updateBaseInfo(@ApiParam(value = "管理员信息", required = true) @Validated @RequestBody PlayPersonnelAdminInfoEditBaseInfoVo vo) {
 
         //校验对应用户是否存在
         SysUserEntity sysUserEntity = sysUserService.selectUserById(vo.getSysUserId());
@@ -117,6 +143,11 @@ public class PlayPersonnelAdminInfoController {
     /**
      * 删除管理员管理
      */
+    @ApiOperation(value = "删除管理员信息", notes = "根据ID批量删除管理员信息")
+    @ApiImplicitParam(name = "ids", value = "管理员ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功")
+    })
     @PreAuthorize("@customSs.hasPermission('play:info:remove')")
     @Log(title = "管理员管理", businessType = BusinessType.DELETE)
     @DeleteMapping("/{ids}")

play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelGroupInfoController.java

@@ -19,6 +19,12 @@ import com.starry.common.enums.BusinessType;
 import com.starry.common.result.R;
 import com.starry.common.utils.ConvertUtil;
 import com.starry.common.utils.IdUtils;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
@@ -32,6 +38,7 @@ import java.util.List;
  * @author admin
  * @since 2024-05-31
  */
+@Api(tags = "店员分组管理", description = "店员分组信息管理相关接口，包括查询、新增、修改和删除等操作")
 @RestController
 @RequestMapping("/personnel/group")
 public class PlayPersonnelGroupInfoController {
@@ -57,8 +64,12 @@ public class PlayPersonnelGroupInfoController {
     /**
      * 查询店员分类信息列表
      */
+    @ApiOperation(value = "分页查询分组列表", notes = "分页查询店员分组信息列表")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功", response = PlayPersonnelGroupInfoReturnVo.class, responseContainer = "Page")
+    })
     @PostMapping("/listByPage")
-    public R listByPage(@Validated @RequestBody PlayPersonnelGroupInfoQueryVo vo) {
+    public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayPersonnelGroupInfoQueryVo vo) {
         IPage<PlayPersonnelGroupInfoReturnVo> list = playClerkGroupInfoService.selectByPage(vo);
         for (PlayPersonnelGroupInfoReturnVo record : list.getRecords()) {
             List<PlayClerkUserInfoEntity> clerkUserInfoEntities = playClerkUserInfoService.listAllByGroupId(record.getId());
@@ -78,9 +89,14 @@ public class PlayPersonnelGroupInfoController {
     /**
      * 新增店员分组信息
      */
+    @ApiOperation(value = "新增分组信息", notes = "创建新的店员分组信息")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "添加失败，包含详细错误信息")
+    })
     @Log(title = "店员分组信息", businessType = BusinessType.INSERT)
     @PostMapping("/createBaseInfo")
-    public R createBaseInfo(@Validated @RequestBody PlayPersonnelGroupInfoEditAddInfoVo vo) {
+    public R createBaseInfo(@ApiParam(value = "分组信息", required = true) @Validated @RequestBody PlayPersonnelGroupInfoEditAddInfoVo vo) {
         //校验对应用户是否存在
         SysUserEntity sysUserEntity = sysUserService.selectUserById(vo.getSysUserId());
         //校验当前用户是否已经是组长
@@ -105,9 +121,14 @@ public class PlayPersonnelGroupInfoController {
     /**
      * 修改店员分组信息
      */
+    @ApiOperation(value = "修改分组信息", notes = "修改店员分组基本信息")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "修改失败，包含详细错误信息")
+    })
     @Log(title = "店员分组信息", businessType = BusinessType.UPDATE)
     @PostMapping(value = "/updateBaseInfo")
-    public R updateBaseInfo(@Validated @RequestBody PlayPersonnelGroupInfoEditBaseInfoVo vo) {
+    public R updateBaseInfo(@ApiParam(value = "分组信息", required = true) @Validated @RequestBody PlayPersonnelGroupInfoEditBaseInfoVo vo) {
         SysUserEntity sysUserEntity = sysUserService.selectUserById(vo.getSysUserId());
         //校验当前用户是否已经是组长
         PlayPersonnelGroupInfoEntity groupInfoEntity = playClerkGroupInfoService.selectByUserId(vo.getSysUserId());
@@ -130,6 +151,12 @@ public class PlayPersonnelGroupInfoController {
     /**
      * 删除店员分组信息
      */
+    @ApiOperation(value = "删除分组信息", notes = "根据ID批量删除店员分组信息")
+    @ApiImplicitParam(name = "ids", value = "分组ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "删除失败，包含详细错误信息")
+    })
     @Log(title = "店员分组信息", businessType = BusinessType.DELETE)
     @DeleteMapping("/{ids}")
     public R remove(@PathVariable String[] ids) {

play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelUserInfoController.java

@@ -6,6 +6,11 @@ import com.starry.admin.modules.personnel.module.vo.PlayPersonnelUserInfoReturnV
 import com.starry.admin.modules.system.module.entity.SysUserEntity;
 import com.starry.admin.modules.system.service.SysUserService;
 import com.starry.common.result.R;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
@@ -18,6 +23,7 @@ import java.util.List;
  * @author admin
  * @since 2024-06-14
  */
+@Api(tags = "系统用户管理", description = "系统用户信息管理相关接口，包括查询等操作")
 @RestController
 @RequestMapping("/personnel/user")
 public class PlayPersonnelUserInfoController {
@@ -29,8 +35,12 @@ public class PlayPersonnelUserInfoController {
     /**
      * 分页查询账户信息列表
      */
+    @ApiOperation(value = "分页查询用户列表", notes = "分页查询系统用户信息列表")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功", response = PlayPersonnelUserInfoReturnVo.class, responseContainer = "Page")
+    })
     @PostMapping("/listByPage")
-    public R listByPage(@Validated @RequestBody PlayPersonnelUserInfoQueryVo vo) {
+    public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayPersonnelUserInfoQueryVo vo) {
         IPage<PlayPersonnelUserInfoReturnVo> list = sysUserService.selectByPage(vo);
         return R.ok(list);
     }
@@ -39,6 +49,10 @@ public class PlayPersonnelUserInfoController {
     /**
      * 查询所有账户信息列表
      */
+    @ApiOperation(value = "查询所有用户", notes = "查询所有系统用户信息")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功", response = SysUserEntity.class, responseContainer = "List")
+    })
     @GetMapping("/listAll")
     public R listAll() {
         List<SysUserEntity> list = sysUserService.selectAll();

play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelWaiterInfoController.java

@@ -16,6 +16,12 @@ import com.starry.common.annotation.Log;
 import com.starry.common.enums.BusinessType;
 import com.starry.common.result.R;
 import com.starry.common.utils.ConvertUtil;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
+import io.swagger.annotations.ApiResponse;
+import io.swagger.annotations.ApiResponses;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
@@ -28,6 +34,7 @@ import java.time.LocalDateTime;
  * @author admin
  * @since 2024-06-14
  */
+@Api(tags = "客服管理", description = "客服信息管理相关接口，包括查询、新增、修改和删除等操作")
 @RestController
 @RequestMapping("/personnel/waiter")
 public class PlayPersonnelWaiterInfoController {
@@ -48,8 +55,12 @@ public class PlayPersonnelWaiterInfoController {
     /**
      * 查询客服信息列表
      */
+    @ApiOperation(value = "分页查询客服列表", notes = "分页查询客服信息列表")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功", response = PlayPersonnelWaiterInfoReturnVo.class, responseContainer = "Page")
+    })
     @PostMapping("/listByPage")
-    public R listByPage(@Validated @RequestBody PlayPersonnelWaiterInfoQueryVo vo) {
+    public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayPersonnelWaiterInfoQueryVo vo) {
         IPage<PlayPersonnelWaiterInfoReturnVo> list = playClerkWaiterInfoService.selectByPage(vo);
         return R.ok(list);
     }
@@ -57,9 +68,14 @@ public class PlayPersonnelWaiterInfoController {
     /**
      * 新增客服信息列表
      */
+    @ApiOperation(value = "新增客服信息", notes = "创建新的客服信息")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "添加失败，包含详细错误信息")
+    })
     @Log(title = "客服管理信息", businessType = BusinessType.INSERT)
     @PostMapping("/createBaseInfo")
-    public R createBaseInfo(@Validated @RequestBody PlayPersonnelWaiterInfoEditAddInfoVo vo) {
+    public R createBaseInfo(@ApiParam(value = "客服信息", required = true) @Validated @RequestBody PlayPersonnelWaiterInfoEditAddInfoVo vo) {
         //校验对应用户是否存在
         SysUserEntity sysUserEntity = sysUserService.selectUserById(vo.getSysUserId());
         //校验当前用户是否已经是组长
@@ -83,9 +99,14 @@ public class PlayPersonnelWaiterInfoController {
     /**
      * 修改客服信息列表
      */
+    @ApiOperation(value = "修改客服信息", notes = "修改客服基本信息")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "修改失败，包含详细错误信息")
+    })
     @Log(title = "客服管理信息", businessType = BusinessType.UPDATE)
     @PostMapping(value = "/updateBaseInfo")
-    public R updateBaseInfo(@Validated @RequestBody PlayPersonnelWaiterInfoEditBaseInfoVo vo) {
+    public R updateBaseInfo(@ApiParam(value = "客服信息", required = true) @Validated @RequestBody PlayPersonnelWaiterInfoEditBaseInfoVo vo) {
 
         //校验对应用户是否存在
         SysUserEntity sysUserEntity = sysUserService.selectUserById(vo.getSysUserId());
@@ -111,6 +132,12 @@ public class PlayPersonnelWaiterInfoController {
     /**
      * 删除客服信息
      */
+    @ApiOperation(value = "删除客服信息", notes = "根据ID批量删除客服信息")
+    @ApiImplicitParam(name = "ids", value = "客服ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3")
+    @ApiResponses({
+        @ApiResponse(code = 200, message = "操作成功"),
+        @ApiResponse(code = 500, message = "删除失败，包含详细错误信息")
+    })
     @Log(title = "客服信息", businessType = BusinessType.DELETE)
     @DeleteMapping("/{ids}")
     public R remove(@PathVariable String[] ids) {

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditAddInfoVo.java

@@ -1,5 +1,7 @@
 package com.starry.admin.modules.personnel.module.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.hibernate.validator.constraints.Length;
 
@@ -12,12 +14,14 @@ import javax.validation.constraints.NotBlank;
  * @since 2024/6/14 14:45
  **/
 @Data
+@ApiModel(value = "新增分组参数", description = "新增店员分组信息的请求参数")
 public class PlayPersonnelGroupInfoEditAddInfoVo {
 
     /**
      * 分组名称
      */
     @NotBlank(message = "用户ID不能为空")
+    @ApiModelProperty(value = "用户ID", required = true, example = "1", notes = "系统用户ID")
     private String sysUserId;
 
 
@@ -26,6 +30,7 @@ public class PlayPersonnelGroupInfoEditAddInfoVo {
      */
     @NotBlank(message = "分组名称不能为空")
     @Length(min = 1, max = 100, message = "字符长度在1-100之间")
+    @ApiModelProperty(value = "分组名称", required = true, example = "销售组", notes = "分组的名称，1-100字符")
     private String groupName;
 
     /**
@@ -33,6 +38,7 @@ public class PlayPersonnelGroupInfoEditAddInfoVo {
      */
     @NotBlank(message = "组长名称不能为空")
     @Length(min = 1, max = 100, message = "字符长度在1-100之间")
+    @ApiModelProperty(value = "组长名称", required = true, example = "张三", notes = "组长的名称，1-100字符")
     private String leaderName;
 
 

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditBaseInfoVo.java

@@ -1,5 +1,7 @@
 package com.starry.admin.modules.personnel.module.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.hibernate.validator.constraints.Length;
 
@@ -12,6 +14,7 @@ import javax.validation.constraints.NotBlank;
  * @since 2024/6/14 14:45
  **/
 @Data
+@ApiModel(value = "修改分组参数", description = "修改店员分组信息的请求参数")
 public class PlayPersonnelGroupInfoEditBaseInfoVo {
     /**
      * UUID
@@ -19,6 +22,7 @@ public class PlayPersonnelGroupInfoEditBaseInfoVo {
      * @since 2024/6/14 16:08
      **/
     @NotBlank(message = "ID不能为空")
+    @ApiModelProperty(value = "分组ID", required = true, example = "1", notes = "需要修改的分组ID")
     private String id;
 
 
@@ -26,6 +30,7 @@ public class PlayPersonnelGroupInfoEditBaseInfoVo {
      * 分组名称
      */
     @NotBlank(message = "用户ID不能为空")
+    @ApiModelProperty(value = "用户ID", required = true, example = "1", notes = "系统用户ID")
     private String sysUserId;
 
 
@@ -34,6 +39,7 @@ public class PlayPersonnelGroupInfoEditBaseInfoVo {
      */
     @NotBlank(message = "分组名称不能为空")
     @Length(min = 1, max = 100, message = "字符长度在1-100之间")
+    @ApiModelProperty(value = "分组名称", required = true, example = "销售组", notes = "分组的名称，1-100字符")
     private String groupName;
 
     /**
@@ -41,6 +47,7 @@ public class PlayPersonnelGroupInfoEditBaseInfoVo {
      */
     @NotBlank(message = "组长名称不能为空")
     @Length(min = 1, max = 100, message = "字符长度在1-100之间")
+    @ApiModelProperty(value = "组长名称", required = true, example = "张三", notes = "组长的名称，1-100字符")
     private String leaderName;
 
 

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoQueryVo.java

@@ -1,6 +1,8 @@
 package com.starry.admin.modules.personnel.module.vo;
 
 import com.starry.common.domain.BasePageEntity;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
@@ -12,11 +14,13 @@ import lombok.EqualsAndHashCode;
  **/
 @EqualsAndHashCode(callSuper = true)
 @Data
+@ApiModel(value = "分组查询参数", description = "查询店员分组信息的条件参数")
 public class PlayPersonnelGroupInfoQueryVo extends BasePageEntity {
 
     /**
      * 分组名称
      */
+    @ApiModelProperty(value = "组长名称", example = "张三", notes = "组长的名称，支持模糊查询")
     private String leaderName;
 
 

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoReturnVo.java

@@ -1,6 +1,8 @@
 package com.starry.admin.modules.personnel.module.vo;
 
 import com.fasterxml.jackson.annotation.JsonFormat;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.springframework.format.annotation.DateTimeFormat;
 
@@ -13,61 +15,72 @@ import java.time.LocalDateTime;
  * @since 2024/6/14 14:45
  **/
 @Data
+@ApiModel(value = "分组返回数据", description = "店员分组信息的返回数据")
 public class PlayPersonnelGroupInfoReturnVo {
 
 
     /**
      * UUID
      */
+    @ApiModelProperty(value = "分组ID", example = "1")
     private String id;
 
 
     /**
      * 租户ID
      */
+    @ApiModelProperty(value = "租户ID", example = "1")
     private String tenantId;
 
     /**
      * 用户ID
      **/
+    @ApiModelProperty(value = "用户ID", example = "1")
     private String sysUserId;
     
     /**
      * 用户账号
      **/
+    @ApiModelProperty(value = "用户账号", example = "admin")
     private String sysUserCode;
 
     /**
      * 分组名称
      */
+    @ApiModelProperty(value = "分组名称", example = "销售组")
     private String groupName;
 
 
     /**
      * 组长名称
      **/
+    @ApiModelProperty(value = "组长名称", example = "张三")
     private String leaderName;
 
 
     /**
      * 排序
      */
+    @ApiModelProperty(value = "排序", example = "1")
     private Long sort;
 
 
     /**
      * 员工总数量
      **/
+    @ApiModelProperty(value = "员工总数", example = "10")
     private Integer totalEmployeesNumber;
 
     /**
      * 上架员工数量
      **/
+    @ApiModelProperty(value = "上架员工数", example = "5")
     private Integer listingEmployeesNumber;
 
 
     @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
+    @ApiModelProperty(value = "添加时间", example = "2024-01-01 12:00:00")
     private LocalDateTime addTime;
 
 

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoQueryVo.java

@@ -1,6 +1,8 @@
 package com.starry.admin.modules.personnel.module.vo;
 
 import com.starry.common.domain.BasePageEntity;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
@@ -12,31 +14,37 @@ import java.util.List;
  **/
 @EqualsAndHashCode(callSuper = true)
 @Data
+@ApiModel(value = "用户查询参数", description = "查询系统用户信息的条件参数")
 public class PlayPersonnelUserInfoQueryVo extends BasePageEntity {
 
 
     /**
      * 用户ID
      */
+    @ApiModelProperty(value = "系统用户ID", example = "1")
     private String sysUserId;
 
 
     /**
      * 用户名称
      */
+    @ApiModelProperty(value = "用户账号", example = "admin", notes = "用户登录账号")
     private String userCode;
 
     /**
      * 角色类型[0:用户;1:店员;2:组长]
      */
+    @ApiModelProperty(value = "角色类型", example = "0", notes = "角色类型[0:用户;1:店员;2:组长]")
     private String ruleType;
 
 
     /**
      * 用户ID
      */
+    @ApiModelProperty(value = "用户ID", example = "1")
     private String userId;
 
 
+    @ApiModelProperty(value = "添加时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "用户添加时间范围，包含开始和结束时间")
     private List<String> addTime;
 }

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoReturnVo.java

@@ -1,5 +1,7 @@
 package com.starry.admin.modules.personnel.module.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 
 /**
@@ -7,28 +9,35 @@ import lombok.Data;
  * @since 2024/6/15 下午9:42
  **/
 @Data
+@ApiModel(value = "用户返回数据", description = "系统用户信息的返回数据")
 public class PlayPersonnelUserInfoReturnVo {
     /**
      * 店员ID
      */
+    @ApiModelProperty(value = "店员ID", example = "1")
     private String clerkId;
 
     /**
      * 店员昵称
      */
+    @ApiModelProperty(value = "店员昵称", example = "小明")
     private String clerkNickname;
 
     /**
      * 店员头像
      */
+    @ApiModelProperty(value = "店员头像", example = "https://example.com/avatar.jpg")
     private String clerkAvatar;
 
+    @ApiModelProperty(value = "用户ID", example = "1")
     private String userId;
 
+    @ApiModelProperty(value = "用户账号", example = "admin")
     private String userCode;
 
     /**
      * 创建时间
      */
+    @ApiModelProperty(value = "创建时间", example = "2024-01-01 12:00:00")
     private String addTime;
 }

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditAddInfoVo.java

@@ -1,5 +1,7 @@
 package com.starry.admin.modules.personnel.module.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.hibernate.validator.constraints.Length;
 
@@ -12,12 +14,14 @@ import javax.validation.constraints.NotBlank;
  * @since 2024/6/14 14:45
  **/
 @Data
+@ApiModel(value = "新增客服参数", description = "新增客服信息的请求参数")
 public class PlayPersonnelWaiterInfoEditAddInfoVo {
 
     /**
      * 分组名称
      */
     @NotBlank(message = "用户ID不能为空")
+    @ApiModelProperty(value = "用户ID", required = true, example = "1", notes = "系统用户ID")
     private String sysUserId;
 
 
@@ -26,6 +30,7 @@ public class PlayPersonnelWaiterInfoEditAddInfoVo {
      */
     @NotBlank(message = "客服名称不能为空")
     @Length(min = 1, max = 100, message = "字符长度在1-100之间")
+    @ApiModelProperty(value = "客服名称", required = true, example = "张三", notes = "客服的名称，1-100字符")
     private String waiterName;
 
 

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditBaseInfoVo.java

@@ -1,5 +1,7 @@
 package com.starry.admin.modules.personnel.module.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.hibernate.validator.constraints.Length;
 
@@ -12,6 +14,7 @@ import javax.validation.constraints.NotBlank;
  * @since 2024/6/14 14:45
  **/
 @Data
+@ApiModel(value = "修改客服参数", description = "修改客服信息的请求参数")
 public class PlayPersonnelWaiterInfoEditBaseInfoVo {
     /**
      * UUID
@@ -19,6 +22,7 @@ public class PlayPersonnelWaiterInfoEditBaseInfoVo {
      * @since 2024/6/14 16:08
      **/
     @NotBlank(message = "ID不能为空")
+    @ApiModelProperty(value = "客服ID", required = true, example = "1", notes = "需要修改的客服ID")
     private String id;
 
 
@@ -26,6 +30,7 @@ public class PlayPersonnelWaiterInfoEditBaseInfoVo {
      * 分组名称
      */
     @NotBlank(message = "用户ID不能为空")
+    @ApiModelProperty(value = "用户ID", required = true, example = "1", notes = "系统用户ID")
     private String sysUserId;
 
     /**
@@ -33,6 +38,7 @@ public class PlayPersonnelWaiterInfoEditBaseInfoVo {
      */
     @NotBlank(message = "客服名称不能为空")
     @Length(min = 1, max = 100, message = "字符长度在1-100之间")
+    @ApiModelProperty(value = "客服名称", required = true, example = "张三", notes = "客服的名称，1-100字符")
     private String waiterName;
 
 

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoQueryVo.java

@@ -1,6 +1,8 @@
 package com.starry.admin.modules.personnel.module.vo;
 
 import com.starry.common.domain.BasePageEntity;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
@@ -12,11 +14,13 @@ import lombok.EqualsAndHashCode;
  **/
 @EqualsAndHashCode(callSuper = true)
 @Data
+@ApiModel(value = "客服查询参数", description = "查询客服信息的条件参数")
 public class PlayPersonnelWaiterInfoQueryVo extends BasePageEntity {
 
     /**
      * 分组名称
      */
+    @ApiModelProperty(value = "客服名称", example = "张三", notes = "客服的名称，支持模糊查询")
     private String waiterName;
 
 

play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoReturnVo.java

@@ -1,6 +1,8 @@
 package com.starry.admin.modules.personnel.module.vo;
 
 import com.fasterxml.jackson.annotation.JsonFormat;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
 import org.springframework.format.annotation.DateTimeFormat;
 
@@ -13,38 +15,45 @@ import java.time.LocalDateTime;
  * @since 2024/6/14 14:45
  **/
 @Data
+@ApiModel(value = "客服返回数据", description = "客服信息的返回数据")
 public class PlayPersonnelWaiterInfoReturnVo {
 
 
     /**
      * UUID
      */
+    @ApiModelProperty(value = "客服ID", example = "1")
     private String id;
 
 
     /**
      * 租户ID
      */
+    @ApiModelProperty(value = "租户ID", example = "1")
     private String tenantId;
 
     /**
      * 用户ID
      **/
+    @ApiModelProperty(value = "用户ID", example = "1")
     private String sysUserId;
 
     /**
      * 用户账号
      **/
+    @ApiModelProperty(value = "用户账号", example = "admin")
     private String sysUserCode;
 
     /**
      * 客户名称
      */
+    @ApiModelProperty(value = "客服名称", example = "张三")
     private String waiterName;
 
 
     @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
+    @ApiModelProperty(value = "添加时间", example = "2024-01-01 12:00:00")
     private LocalDateTime addTime;