From d5a51faf8bba60928444be67d5ef27dddd80f070 Mon Sep 17 00:00:00 2001 From: huchuansai Date: Thu, 12 Jun 2025 10:23:22 +0800 Subject: [PATCH] docs: swagger docs refacto & perf --- list_OpenAPI.json | 246 ++++++++++++++++++ .../PlayAvatarFrameInfoController.java | 51 +++- .../PlayClerkArticleInfoController.java | 26 +- ...PlayClerkClassificationInfoController.java | 43 ++- .../PlayClerkCommodityController.java | 43 ++- .../PlayClerkDataReviewInfoController.java | 25 +- .../PlayClerkLevelInfoController.java | 36 ++- .../controller/PlayClerkPkController.java | 38 ++- .../PlayClerkRankingInfoController.java | 39 ++- .../PlayClerkTypeInfoController.java | 38 ++- .../PlayClerkUserInfoController.java | 75 +++++- .../PlayClerkUserReviewInfoController.java | 25 +- .../PlayClerkWagesDetailsInfoController.java | 39 ++- .../PlayClerkWagesInfoController.java | 26 +- .../PlayCustomArticleInfoController.java | 39 ++- .../module/entity/PlayClerkUserQueryVo.java | 25 ++ .../module/entity/PlayClerkUserReturnVo.java | 39 +++ .../entity/PlayClerkUserTypeEditVo.java | 5 + .../module/vo/PlayAvatarFrameInfoAddVo.java | 10 + .../module/vo/PlayAvatarFrameInfoQueryVo.java | 3 + .../module/vo/PlayAvatarFrameSendVo.java | 5 + .../module/vo/PlayClerkArticleQueryVo.java | 8 + .../module/vo/PlayClerkArticleReturnVo.java | 15 ++ .../vo/PlayClerkArticleReviewStateEditVo.java | 7 + .../module/vo/PlayClerkCommodityQueryVo.java | 5 + .../module/vo/PlayClerkDataReviewQueryVo.java | 7 + .../vo/PlayClerkDataReviewReturnVo.java | 15 ++ .../vo/PlayClerkDataReviewStateEditVo.java | 7 + .../clerk/module/vo/PlayClerkLevelAddVo.java | 10 + .../clerk/module/vo/PlayClerkLevelEditVo.java | 15 +- .../module/vo/PlayClerkTypeInfoAddVo.java | 6 + .../module/vo/PlayClerkTypeInfoQueryVo.java | 4 + .../PlayClerkUnsettledWagesInfoQueryVo.java | 5 + .../clerk/module/vo/PlayClerkUserEditVo.java | 19 ++ .../module/vo/PlayClerkUserReviewQueryVo.java | 10 + .../vo/PlayClerkUserReviewReturnVo.java | 24 +- .../vo/PlayClerkUserReviewStateEditVo.java | 7 + .../module/vo/PlayClerkUserStateEditVo.java | 17 ++ .../module/vo/PlayClerkWagesInfoQueryVo.java | 7 + .../PlayCustomFollowInfoController.java | 39 ++- .../PlayCustomGiftInfoController.java | 39 ++- .../PlayCustomLeaveMsgController.java | 39 ++- .../PlayCustomLevelInfoController.java | 36 ++- .../PlayCustomRankingController.java | 12 +- .../PlayCustomUserInfoController.java | 46 +++- .../module/vo/PlayCustomLeaveMsgQueryVo.java | 13 + .../module/vo/PlayCustomLeaveMsgReturnVo.java | 11 + .../module/vo/PlayCustomLevelAddVo.java | 7 + .../module/vo/PlayCustomLevelEditVo.java | 8 + .../module/vo/PlayCustomLevelReturnVo.java | 9 + .../module/vo/PlayCustomRankingQueryVo.java | 5 + .../module/vo/PlayCustomRankingReturnVo.java | 15 ++ .../module/vo/PlayCustomUserQueryVo.java | 21 ++ .../module/vo/PlayCustomUserReturnVo.java | 37 ++- .../module/vo/PlayCustomUserStateEditVo.java | 13 + .../PlayOrderComplaintInfoController.java | 38 ++- .../PlayOrderContinueInfoController.java | 19 +- .../PlayOrderEvaluateInfoController.java | 25 +- .../controller/PlayOrderInfoController.java | 59 ++++- .../PlayOrderRefundInfoController.java | 38 ++- .../PlayOrderRewardInfoController.java | 15 +- .../module/vo/PlayOrderComplaintQueryVo.java | 10 + .../module/vo/PlayOrderComplaintReturnVo.java | 25 ++ .../module/vo/PlayOrderContinueQueryVo.java | 9 + .../module/vo/PlayOrderContinueReturnVo.java | 24 ++ .../module/vo/PlayOrderEditAcceptByVo.java | 6 + .../vo/PlayOrderEditBackendRemarkByVo.java | 5 + .../vo/PlayOrderEditRandomSingleVo.java | 8 + .../vo/PlayOrderEvaluateEditStateVo.java | 5 + .../module/vo/PlayOrderEvaluateQueryVo.java | 10 + .../module/vo/PlayOrderEvaluateReturnVo.java | 28 +- .../order/module/vo/PlayOrderInfoQueryVo.java | 21 ++ .../order/module/vo/PlayOrderRefundAddVo.java | 6 + .../module/vo/PlayOrderRefundQueryVo.java | 12 + .../module/vo/PlayOrderRefundReturnVo.java | 42 +++ .../module/vo/PlayOrderReviewStateEditVo.java | 6 + .../module/vo/PlayOrderRewardQueryVo.java | 12 +- .../module/vo/PlayOrderRewardReturnVo.java | 20 ++ .../PlayBalanceDetailsInfoController.java | 31 ++- .../PlayPersonnelAdminInfoController.java | 37 ++- .../PlayPersonnelGroupInfoController.java | 33 ++- .../PlayPersonnelUserInfoController.java | 16 +- .../PlayPersonnelWaiterInfoController.java | 33 ++- .../PlayPersonnelGroupInfoEditAddInfoVo.java | 6 + .../PlayPersonnelGroupInfoEditBaseInfoVo.java | 7 + .../vo/PlayPersonnelGroupInfoQueryVo.java | 4 + .../vo/PlayPersonnelGroupInfoReturnVo.java | 13 + .../vo/PlayPersonnelUserInfoQueryVo.java | 8 + .../vo/PlayPersonnelUserInfoReturnVo.java | 9 + .../PlayPersonnelWaiterInfoEditAddInfoVo.java | 5 + ...PlayPersonnelWaiterInfoEditBaseInfoVo.java | 6 + .../vo/PlayPersonnelWaiterInfoQueryVo.java | 4 + .../vo/PlayPersonnelWaiterInfoReturnVo.java | 9 + .../PlayClerkGiftInfoController.java | 38 ++- .../PlayCommodityInfoController.java | 47 +++- .../PlayCouponDetailsController.java | 45 +++- .../controller/PlayCouponInfoController.java | 52 +++- .../controller/PlayGiftInfoController.java | 39 ++- .../PlayShopArticleInfoController.java | 32 ++- .../PlayShopCarouselInfoController.java | 39 ++- .../controller/ShopUiSettingController.java | 18 +- .../PlayClerkPerformanceController.java | 24 +- .../vo/PlayClerkPerformanceInfoQueryVo.java | 9 + .../vo/PlayClerkPerformanceInfoReturnVo.java | 32 ++- .../AdministrativeAreaDictInfoController.java | 9 + .../system/controller/CacheController.java | 37 +++ .../system/controller/LoginController.java | 32 ++- .../system/controller/ServerController.java | 9 + .../system/controller/SysDeptController.java | 50 +++- .../system/controller/SysDictController.java | 47 +++- .../controller/SysDictDataController.java | 43 ++- .../controller/SysLoginLogController.java | 34 ++- .../system/controller/SysMenuController.java | 74 ++++-- .../controller/SysOperationLogController.java | 45 +++- .../system/controller/SysRoleController.java | 117 +++++++-- .../system/controller/SysSmsController.java | 15 ++ .../controller/SysTenantController.java | 38 ++- .../SysTenantPackageController.java | 48 +++- .../SysTenantRechargeInfoController.java | 38 ++- .../system/controller/SysUserController.java | 94 +++++-- .../controller/UserOnlineController.java | 21 ++ .../system/module/entity/SysLoginLogVo.java | 12 + .../admin/modules/system/vo/LoginVo.java | 11 +- .../admin/modules/system/vo/MetaVo.java | 10 +- .../admin/modules/system/vo/RouterVo.java | 19 +- .../modules/system/vo/SysOperationLogVo.java | 22 +- .../admin/modules/system/vo/SysRoleAddVo.java | 15 ++ .../system/vo/SysUserEntityListVo.java | 8 + .../modules/system/vo/SysUserQueryVo.java | 25 +- .../system/vo/UpdateUserMobileParam.java | 12 + .../system/vo/UpdateUserPasswordParam.java | 8 + .../admin/modules/system/vo/UserAddParam.java | 8 + .../admin/modules/system/vo/UserQueryVo.java | 8 +- .../controller/WxArticleController.java | 53 +++- .../WxClerkCommodityController.java | 21 ++ .../weichat/controller/WxClerkController.java | 49 +++- .../controller/WxClerkLeveController.java | 9 + .../controller/WxClerkTypeController.java | 9 + .../controller/WxClerkWagesController.java | 24 ++ .../controller/WxCommodityController.java | 11 + .../controller/WxCommonController.java | 27 +- .../controller/WxCouponController.java | 24 +- .../controller/WxCustomController.java | 54 +++- .../weichat/controller/WxGiftController.java | 22 ++ .../weichat/controller/WxLevelController.java | 9 + .../weichat/controller/WxOauthController.java | 75 +++++- .../controller/WxOrderInfoController.java | 52 +++- .../WxPersonnelGroupInfoController.java | 12 +- .../weichat/controller/WxPlayController.java | 29 ++- .../WxPlayOrderRankingController.java | 13 + .../weichat/controller/WxShopController.java | 20 +- .../weichat/controller/WxSmsController.java | 11 + .../clerk/PlayClerkUserInfoQueryVo.java | 13 + .../clerk/PlayClerkUserInfoResultVo.java | 26 ++ .../starry/common/domain/BasePageEntity.java | 11 + 155 files changed, 3655 insertions(+), 281 deletions(-) create mode 100644 list_OpenAPI.json diff --git a/list_OpenAPI.json b/list_OpenAPI.json new file mode 100644 index 0000000..66dbbfc --- /dev/null +++ b/list_OpenAPI.json @@ -0,0 +1,246 @@ +{ + "swagger": "2.0", + "info": { + "description": "# 接口文档", + "version": "1.0", + "title": "接口文档", + "termsOfService": "http://www.xx.com/", + "contact": { + "name": "277769738@qq.com" + } + }, + "host": "localhost:7002", + "basePath": "/api", + "schemes": [], + "consumes": [ + "*/*" + ], + "produces": [ + "*/*" + ], + "paths": { + "/api/clerk/user/list": { + "get": { + "tags": [ + "play-clerk-user-info-controller" + ], + "summary": "list", + "operationId": "listUsingGET_5", + "produces": [ + "*/*" + ], + "parameters": [ + { + "name": "beginTime", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "clerkState", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "createdBy", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "createdTime", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + }, + { + "name": "currentPage", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "deleted", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "endTime", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "levelId", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "listingState", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "nickname", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "onboardingState", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "pageNum", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "phone", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "province", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "recommendationState", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "sex", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "typeId", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "updatedBy", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "updatedTime", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "originalRef": "全局统一返回结果", + "$ref": "#/definitions/全局统一返回结果" + } + }, + "401": { + "description": "Unauthorized" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not Found" + } + }, + "deprecated": false + } + } + }, + "definitions": { + "全局统一返回结果": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32", + "description": "返回码" + }, + "data": { + "type": "object", + "description": "返回数据" + }, + "message": { + "type": "string", + "description": "返回消息" + }, + "pageInfo": { + "description": "分页信息", + "originalRef": "PageInfo", + "$ref": "#/definitions/PageInfo" + }, + "success": { + "type": "boolean", + "description": "是否成功" + }, + "total": { + "type": "integer", + "format": "int64", + "description": "总条数" + } + }, + "title": "全局统一返回结果" + }, + "PageInfo": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "format": "int32", + "description": "当前页", + "refType": null + }, + "pageSize": { + "type": "integer", + "format": "int32", + "description": "页大小", + "refType": null + }, + "totalCount": { + "type": "integer", + "format": "int64", + "description": "总记录数", + "refType": null + }, + "totalPage": { + "type": "integer", + "format": "int64", + "description": "总页数", + "refType": null + } + }, + "title": "PageInfo" + } + } +} \ No newline at end of file diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayAvatarFrameInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayAvatarFrameInfoController.java index 24a529b..6f762d7 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayAvatarFrameInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayAvatarFrameInfoController.java @@ -11,6 +11,13 @@ 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.ApiImplicitParams; +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.*; import org.springframework.web.multipart.MultipartFile; @@ -24,6 +31,7 @@ import java.io.IOException; * @author admin * @since 2024-06-06 */ +@Api(tags = "店员头像框管理", description = "店员头像框信息管理相关接口，包括查询、新增、修改、删除和赠送等操作") @RestController @RequestMapping("/clerk/avatarFrame") public class PlayAvatarFrameInfoController { @@ -35,22 +43,34 @@ public class PlayAvatarFrameInfoController { private IOssFileService ossFileService; + @ApiOperation(value = "分页查询头像框", notes = "分页查询店员头像框信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayAvatarFrameInfoEntity.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayAvatarFrameInfoQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayAvatarFrameInfoQueryVo vo) { return R.ok(playAvatarFrameInfoService.selectByPage(vo)); } /** * 查询店员头像框列表 */ + @ApiOperation(value = "查询所有头像框", notes = "获取所有店员头像框信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayAvatarFrameInfoEntity.class, responseContainer = "List") + }) @GetMapping("/listAll") public R listAll() { return R.ok(playAvatarFrameInfoService.selectAll()); } + @ApiOperation(value = "上传头像框图片", notes = "上传店员头像框图片文件") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class, responseContainer = "R") + }) @PostMapping("/uploadFile") - public R uploadFile(@RequestParam("file") MultipartFile file) throws IOException { + public R uploadFile(@ApiParam(value = "图片文件", required = true) @RequestParam("file") MultipartFile file) throws IOException { String fileAddress = ossFileService.upload(file.getInputStream(), SecurityUtils.getTenantId(), file.getOriginalFilename()); return R.ok(fileAddress); } @@ -59,9 +79,14 @@ public class PlayAvatarFrameInfoController { /** * 新增店员头像框 */ + @ApiOperation(value = "新增头像框", notes = "创建新的店员头像框信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "店员头像框", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@Validated @RequestBody PlayAvatarFrameInfoAddVo vo) { + public R create(@ApiParam(value = "头像框信息", required = true) @Validated @RequestBody PlayAvatarFrameInfoAddVo vo) { boolean success = playAvatarFrameInfoService.create(ConvertUtil.entityToVo(vo, PlayAvatarFrameInfoEntity.class)); if (success) { return R.ok(); @@ -72,9 +97,15 @@ public class PlayAvatarFrameInfoController { /** * 修改店员头像框 */ + @ApiOperation(value = "修改头像框", notes = "根据ID修改店员头像框信息") + @ApiImplicitParam(name = "id", value = "头像框ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "店员头像框", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayAvatarFrameInfoEntity playAvatarFrameInfo) { + public R update(@PathVariable String id, @ApiParam(value = "头像框信息", required = true) @RequestBody PlayAvatarFrameInfoEntity playAvatarFrameInfo) { playAvatarFrameInfo.setId(id); boolean success = playAvatarFrameInfoService.update(playAvatarFrameInfo); if (success) { @@ -86,6 +117,11 @@ public class PlayAvatarFrameInfoController { /** * 删除店员头像框 */ + @ApiOperation(value = "删除头像框", notes = "根据ID批量删除店员头像框信息") + @ApiImplicitParam(name = "ids", value = "头像框ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "店员头像框", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { @@ -95,9 +131,14 @@ public class PlayAvatarFrameInfoController { /** * 新增店员头像框 */ + @ApiOperation(value = "赠送头像框", notes = "赠送头像框给指定店员") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "赠送店员头像框", businessType = BusinessType.INSERT) @PostMapping("/sendAvatarFrame") - public R sendAvatarFrame(@Validated @RequestBody PlayAvatarFrameSendVo vo) { + public R sendAvatarFrame(@ApiParam(value = "赠送信息", required = true) @Validated @RequestBody PlayAvatarFrameSendVo vo) { System.out.println(vo); return R.error("添加失败"); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkArticleInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkArticleInfoController.java index e7c58d3..250de66 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkArticleInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkArticleInfoController.java @@ -11,6 +11,13 @@ 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.ApiImplicitParams; +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.*; @@ -22,6 +29,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-04 */ +@Api(tags = "店员动态管理", description = "店员动态信息管理相关接口，包括查询、审核和删除等操作") @RestController @RequestMapping("/clerk/article") public class PlayClerkArticleInfoController { @@ -34,8 +42,12 @@ public class PlayClerkArticleInfoController { /** * 查询店员动态信息列表 */ + @ApiOperation(value = "分页查询动态列表", notes = "分页查询店员动态信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkArticleReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayClerkArticleQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkArticleQueryVo vo) { IPage list = playClerkArticleInfoService.selectByPage(vo,false); return R.ok(list); } @@ -44,10 +56,15 @@ public class PlayClerkArticleInfoController { /** * 修改店员动态信息 */ + @ApiOperation(value = "修改动态审核状态", notes = "更新店员动态审核状态，通过或拒绝") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) //@PreAuthorize("@customSs.hasPermission('clerk:article:update')") @Log(title = "店员动态信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update") - public R update(@RequestBody PlayClerkArticleReviewStateEditVo vo) { + public R update(@ApiParam(value = "审核状态信息", required = true) @RequestBody PlayClerkArticleReviewStateEditVo vo) { PlayClerkArticleInfoEntity entity = ConvertUtil.entityToVo(vo, PlayClerkArticleInfoEntity.class); boolean success = playClerkArticleInfoService.update(entity); if (success) { @@ -59,6 +76,11 @@ public class PlayClerkArticleInfoController { /** * 删除店员动态信息 */ + @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('clerk:article:delete')") @Log(title = "店员动态信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkClassificationInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkClassificationInfoController.java index a410e28..e0ae785 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkClassificationInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkClassificationInfoController.java @@ -6,6 +6,13 @@ import com.starry.admin.modules.clerk.service.IPlayClerkClassificationInfoServic 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.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; @@ -17,6 +24,7 @@ import java.util.List; * @author admin * @since 2024-04-06 */ +@Api(tags = "店员分类管理", description = "店员分类信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/clerk/class") public class PlayClerkClassificationInfoController { @@ -26,6 +34,10 @@ public class PlayClerkClassificationInfoController { /** * 查询店员分类列表 */ + @ApiOperation(value = "查询所有分类", notes = "获取所有店员分类信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkClassificationInfoEntity.class, responseContainer = "List") + }) @GetMapping("/listAll") public R listAll() { List list = playClerkClassificationInfoService.selectAll(); @@ -36,8 +48,12 @@ public class PlayClerkClassificationInfoController { /** * 查询店员分类列表 */ + @ApiOperation(value = "分页查询分类", notes = "分页查询店员分类信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkClassificationInfoEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayClerkClassificationInfoEntity playClerkClassificationInfo) { + public R list(@ApiParam(value = "查询条件") PlayClerkClassificationInfoEntity playClerkClassificationInfo) { IPage list = playClerkClassificationInfoService.selectPlayClerkClassificationInfoByPage(playClerkClassificationInfo); return R.ok(list); } @@ -45,6 +61,11 @@ public class PlayClerkClassificationInfoController { /** * 获取店员分类详细信息 */ + @ApiOperation(value = "获取分类详情", notes = "根据ID获取店员分类详细信息") + @ApiImplicitParam(name = "id", value = "分类ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkClassificationInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkClassificationInfoService.selectPlayClerkClassificationInfoById(id)); @@ -53,9 +74,14 @@ public class PlayClerkClassificationInfoController { /** * 新增店员分类 */ + @ApiOperation(value = "新增分类", notes = "创建新的店员分类信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "店员分类", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayClerkClassificationInfoEntity playClerkClassificationInfo) { + public R create(@ApiParam(value = "分类信息", required = true) @RequestBody PlayClerkClassificationInfoEntity playClerkClassificationInfo) { boolean success = playClerkClassificationInfoService.create(playClerkClassificationInfo); if (success) { return R.ok(); @@ -66,9 +92,15 @@ public class PlayClerkClassificationInfoController { /** * 修改店员分类 */ + @ApiOperation(value = "修改分类", notes = "根据ID修改店员分类信息") + @ApiImplicitParam(name = "id", value = "分类ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "店员分类", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayClerkClassificationInfoEntity playClerkClassificationInfo) { + public R update(@PathVariable String id, @ApiParam(value = "分类信息", required = true) @RequestBody PlayClerkClassificationInfoEntity playClerkClassificationInfo) { playClerkClassificationInfo.setId(id); boolean success = playClerkClassificationInfoService.update(playClerkClassificationInfo); if (success) { @@ -80,6 +112,11 @@ public class PlayClerkClassificationInfoController { /** * 删除店员分类 */ + @ApiOperation(value = "删除分类", notes = "根据ID批量删除店员分类信息") + @ApiImplicitParam(name = "ids", value = "分类ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "店员分类", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkCommodityController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkCommodityController.java index 9c8399c..81f3576 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkCommodityController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkCommodityController.java @@ -8,6 +8,13 @@ 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.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; @@ -19,6 +26,7 @@ import java.util.List; * @author admin * @since 2024-03-31 */ +@Api(tags = "陪聊服务项目", description = "陪聊服务项目管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/clerk/commodity") public class PlayClerkCommodityController { @@ -28,6 +36,10 @@ public class PlayClerkCommodityController { /** * 查询陪聊服务项目列表 */ + @ApiOperation(value = "查询所有服务项目", notes = "获取所有陪聊服务项目列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkCommodityQueryVo.class, responseContainer = "List") + }) @GetMapping("/listAllCommodity") public R listAllCommodity() { List list = playClerkCommodityService.selectAll(); @@ -38,8 +50,12 @@ public class PlayClerkCommodityController { /** * 查询陪聊服务项目列表 */ + @ApiOperation(value = "分页查询服务项目", notes = "分页查询陪聊服务项目列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkCommodityEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayClerkCommodityEntity playClerkCommodity) { + public R list(@ApiParam(value = "查询条件") PlayClerkCommodityEntity playClerkCommodity) { IPage list = playClerkCommodityService.selectPlayClerkCommodityByPage(playClerkCommodity); return R.ok(list); } @@ -47,6 +63,11 @@ public class PlayClerkCommodityController { /** * 获取陪聊服务项目详细信息 */ + @ApiOperation(value = "获取服务项目详情", notes = "根据ID获取陪聊服务项目详细信息") + @ApiImplicitParam(name = "id", value = "服务项目ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkCommodityEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkCommodityService.selectPlayClerkCommodityById(id)); @@ -55,9 +76,14 @@ public class PlayClerkCommodityController { /** * 新增陪聊服务项目 */ + @ApiOperation(value = "新增服务项目", notes = "创建新的陪聊服务项目") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "陪聊服务项目", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayClerkCommodityEntity playClerkCommodity) { + public R create(@ApiParam(value = "服务项目信息", required = true) @RequestBody PlayClerkCommodityEntity playClerkCommodity) { boolean success = playClerkCommodityService.create(playClerkCommodity); if (success) { return R.ok(); @@ -69,9 +95,15 @@ public class PlayClerkCommodityController { /** * 修改陪聊服务项目 */ + @ApiOperation(value = "修改服务项目", notes = "根据ID修改陪聊服务项目信息") + @ApiImplicitParam(name = "id", value = "服务项目ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "陪聊服务项目", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayClerkCommodityEntity playClerkCommodity) { + public R update(@PathVariable String id, @ApiParam(value = "服务项目信息", required = true) @RequestBody PlayClerkCommodityEntity playClerkCommodity) { playClerkCommodity.setId(id); boolean success = playClerkCommodityService.update(playClerkCommodity); if (success) { @@ -83,6 +115,11 @@ public class PlayClerkCommodityController { /** * 删除陪聊服务项目 */ + @ApiOperation(value = "删除服务项目", notes = "根据ID批量删除陪聊服务项目") + @ApiImplicitParam(name = "ids", value = "服务项目ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "陪聊服务项目", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkDataReviewInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkDataReviewInfoController.java index f7391db..b35e2b6 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkDataReviewInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkDataReviewInfoController.java @@ -8,6 +8,13 @@ import com.starry.admin.modules.clerk.service.IPlayClerkDataReviewInfoService; 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.ApiImplicitParams; +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.*; @@ -19,6 +26,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-19 */ +@Api(tags = "店员资料内容审核", description = "店员资料内容审核相关接口，包括昵称、头像、相册、录音等资料的审核") @RestController @RequestMapping("/clerk/data/review") public class PlayClerkDataReviewInfoController { @@ -30,8 +38,12 @@ public class PlayClerkDataReviewInfoController { /** * 查询店员资料审核列表 */ + @ApiOperation(value = "查询资料审核列表", notes = "分页查询店员资料审核列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkDataReviewReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayClerkDataReviewQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkDataReviewQueryVo vo) { IPage list = playClerkDataReviewInfoService.selectByPage(vo); return R.ok(list); } @@ -39,10 +51,14 @@ public class PlayClerkDataReviewInfoController { /** * 修改店员资料审核 */ + @ApiOperation(value = "修改资料审核状态", notes = "更新店员资料审核状态，通过或拒绝") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) //@PreAuthorize("@customSs.hasPermission('clerk:dataReview:update')") @Log(title = "店员资料审核", businessType = BusinessType.UPDATE) @PostMapping(value = "/update") - public R update(@Validated @RequestBody PlayClerkDataReviewStateEditVo vo) { + public R update(@ApiParam(value = "审核状态信息", required = true) @Validated @RequestBody PlayClerkDataReviewStateEditVo vo) { playClerkDataReviewInfoService.updateDataReviewState(vo); return R.ok(); } @@ -50,6 +66,11 @@ public class PlayClerkDataReviewInfoController { /** * 删除店员资料审核 */ + @ApiOperation(value = "删除资料审核记录", notes = "根据ID批量删除店员资料审核记录") + @ApiImplicitParam(name = "ids", value = "审核记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) //@PreAuthorize("@customSs.hasPermission('clerk:dataReview:delete')") @Log(title = "店员资料审核", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkLevelInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkLevelInfoController.java index a296cef..c20b985 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkLevelInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkLevelInfoController.java @@ -9,6 +9,13 @@ 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.ApiImplicitParams; +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.*; @@ -20,6 +27,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-03-30 */ +@Api(tags = "店员等级管理", description = "店员等级信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/clerk/level") public class PlayClerkLevelInfoController { @@ -29,6 +37,10 @@ public class PlayClerkLevelInfoController { /** * 查询店员等级列表 */ + @ApiOperation(value = "查询所有等级", notes = "获取所有店员等级信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkLevelInfoEntity.class, responseContainer = "List") + }) @GetMapping("/listAll") public R listAll() { return R.ok(playClerkLevelInfoService.selectAll()); @@ -37,6 +49,11 @@ public class PlayClerkLevelInfoController { /** * 获取店员等级详细信息 */ + @ApiOperation(value = "获取等级详情", notes = "根据ID获取店员等级详细信息") + @ApiImplicitParam(name = "id", value = "等级ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkLevelInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkLevelInfoService.selectPlayClerkLevelInfoById(id)); @@ -45,9 +62,14 @@ public class PlayClerkLevelInfoController { /** * 新增店员等级 */ + @ApiOperation(value = "新增等级", notes = "创建新的店员等级信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "店员等级", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayClerkLevelAddVo vo) { + public R create(@ApiParam(value = "等级信息", required = true) @RequestBody PlayClerkLevelAddVo vo) { PlayClerkLevelInfoEntity entity = ConvertUtil.entityToVo(vo, PlayClerkLevelInfoEntity.class); int level = playClerkLevelInfoService.selectMaxLevel(); entity.setLevel(level + 1); @@ -61,9 +83,14 @@ public class PlayClerkLevelInfoController { /** * 修改店员等级 */ + @ApiOperation(value = "修改等级", notes = "修改店员等级信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "店员等级", businessType = BusinessType.UPDATE) @PostMapping(value = "/update") - public R update(@Validated @RequestBody PlayClerkLevelEditVo vo) { + public R update(@ApiParam(value = "等级信息", required = true) @Validated @RequestBody PlayClerkLevelEditVo vo) { PlayClerkLevelInfoEntity entity = ConvertUtil.entityToVo(vo, PlayClerkLevelInfoEntity.class); boolean success = playClerkLevelInfoService.update(entity); if (success) { @@ -75,6 +102,11 @@ public class PlayClerkLevelInfoController { /** * 删除店员等级 */ + @ApiOperation(value = "删除最高等级", notes = "删除系统中最高的店员等级") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "最后一级,不允许删除") + }) @Log(title = "店员等级", businessType = BusinessType.DELETE) @DeleteMapping("delMaxLevel") public R remove() { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkPkController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkPkController.java index 2d4d1e5..cc40d0e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkPkController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkPkController.java @@ -6,6 +6,12 @@ import com.starry.admin.modules.clerk.service.IPlayClerkPkService; 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.web.bind.annotation.*; import javax.annotation.Resource; @@ -16,6 +22,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-08-02 */ +@Api(tags = "店员PK管理", description = "店员PK信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/play/pk") public class PlayClerkPkController { @@ -25,8 +32,12 @@ public class PlayClerkPkController { /** * 查询店员pk列表 */ + @ApiOperation(value = "分页查询PK列表", notes = "分页查询店员PK信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkPkEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayClerkPkEntity playClerkPk) { + public R list(@ApiParam(value = "查询条件") PlayClerkPkEntity playClerkPk) { IPage list = playClerkPkService.selectPlayClerkPkByPage(playClerkPk); return R.ok(list); } @@ -34,6 +45,11 @@ public class PlayClerkPkController { /** * 获取店员pk详细信息 */ + @ApiOperation(value = "获取PK详情", notes = "根据ID获取店员PK详细信息") + @ApiImplicitParam(name = "id", value = "PK记录ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkPkEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkPkService.selectPlayClerkPkById(id)); @@ -42,9 +58,14 @@ public class PlayClerkPkController { /** * 新增店员pk */ + @ApiOperation(value = "新增PK记录", notes = "创建新的店员PK信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "店员pk", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayClerkPkEntity playClerkPk) { + public R create(@ApiParam(value = "PK信息", required = true) @RequestBody PlayClerkPkEntity playClerkPk) { boolean success = playClerkPkService.create(playClerkPk); if (success) { return R.ok(); @@ -55,9 +76,15 @@ public class PlayClerkPkController { /** * 修改店员pk */ + @ApiOperation(value = "修改PK记录", notes = "根据ID修改店员PK信息") + @ApiImplicitParam(name = "id", value = "PK记录ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "店员pk", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayClerkPkEntity playClerkPk) { + public R update(@PathVariable String id, @ApiParam(value = "PK信息", required = true) @RequestBody PlayClerkPkEntity playClerkPk) { playClerkPk.setId(id); boolean success = playClerkPkService.update(playClerkPk); if (success) { @@ -69,6 +96,11 @@ public class PlayClerkPkController { /** * 删除店员pk */ + @ApiOperation(value = "删除PK记录", notes = "根据ID批量删除店员PK信息") + @ApiImplicitParam(name = "ids", value = "PK记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "店员pk", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkRankingInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkRankingInfoController.java index ada9ecc..105b85d 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkRankingInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkRankingInfoController.java @@ -8,6 +8,13 @@ import com.starry.admin.modules.clerk.service.IPlayClerkRankingInfoService; 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.ApiImplicitParams; +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.*; @@ -19,6 +26,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-25 */ +@Api(tags = "店员排行管理", description = "店员排行榜信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/clerk/ranking") public class PlayClerkRankingInfoController { @@ -28,8 +36,12 @@ public class PlayClerkRankingInfoController { /** * 查询店员排行列表 */ + @ApiOperation(value = "查询排行列表", notes = "分页查询店员排行信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = IPlayClerkRankingInfoReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody IPlayClerkRankingInfoQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody IPlayClerkRankingInfoQueryVo vo) { IPage list = playClerkRankingInfoService.selectByPage(vo); return R.ok(list); } @@ -37,6 +49,11 @@ public class PlayClerkRankingInfoController { /** * 获取店员排行详细信息 */ + @ApiOperation(value = "获取排行详情", notes = "根据ID获取店员排行详细信息") + @ApiImplicitParam(name = "id", value = "排行ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkRankingInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkRankingInfoService.selectPlayClerkRankingInfoById(id)); @@ -45,10 +62,15 @@ public class PlayClerkRankingInfoController { /** * 新增店员排行 */ + @ApiOperation(value = "新增排行", notes = "创建新的店员排行记录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) //@PreAuthorize("@customSs.hasPermission('clerk:ranking:add')") @Log(title = "店员排行", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayClerkRankingInfoEntity playClerkRankingInfo) { + public R create(@ApiParam(value = "排行信息", required = true) @RequestBody PlayClerkRankingInfoEntity playClerkRankingInfo) { boolean success = playClerkRankingInfoService.create(playClerkRankingInfo); if (success) { return R.ok(); @@ -59,10 +81,16 @@ public class PlayClerkRankingInfoController { /** * 修改店员排行 */ + @ApiOperation(value = "修改排行", notes = "根据ID修改店员排行信息") + @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('clerk:ranking:update')") @Log(title = "店员排行", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayClerkRankingInfoEntity playClerkRankingInfo) { + public R update(@PathVariable String id, @ApiParam(value = "排行信息", required = true) @RequestBody PlayClerkRankingInfoEntity playClerkRankingInfo) { playClerkRankingInfo.setId(id); boolean success = playClerkRankingInfoService.update(playClerkRankingInfo); if (success) { @@ -74,6 +102,11 @@ public class PlayClerkRankingInfoController { /** * 删除店员排行 */ + @ApiOperation(value = "删除排行", notes = "根据ID批量删除店员排行信息") + @ApiImplicitParam(name = "ids", value = "排行ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) //@PreAuthorize("@customSs.hasPermission('clerk:ranking:delete')") @Log(title = "店员排行", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkTypeInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkTypeInfoController.java index 97dd99f..0f5dbc3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkTypeInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkTypeInfoController.java @@ -8,6 +8,13 @@ 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.ApiImplicitParams; +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.*; @@ -19,6 +26,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-31 */ +@Api(tags = "店员分类管理", description = "店员分类信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/clerk/type") public class PlayClerkTypeInfoController { @@ -28,13 +36,21 @@ public class PlayClerkTypeInfoController { /** * 查询店员分类信息列表 */ + @ApiOperation(value = "查询所有分类", notes = "获取所有店员分类信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkTypeInfoEntity.class, responseContainer = "List") + }) @GetMapping("/listByAll") public R listByAll() { return R.ok(playClerkTypeInfoService.selectByAll()); } + @ApiOperation(value = "分页查询分类", notes = "分页查询店员分类信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkTypeInfoEntity.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayClerkTypeInfoQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkTypeInfoQueryVo vo) { return R.ok(playClerkTypeInfoService.selectByPage(vo)); } @@ -44,9 +60,14 @@ public class PlayClerkTypeInfoController { /** * 新增店员分类信息 */ + @ApiOperation(value = "新增分类", notes = "创建新的店员分类信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "店员分类信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@Validated @RequestBody PlayClerkTypeInfoAddVo vo) { + public R create(@ApiParam(value = "分类信息", required = true) @Validated @RequestBody PlayClerkTypeInfoAddVo vo) { boolean success = playClerkTypeInfoService.create(ConvertUtil.entityToVo(vo, PlayClerkTypeInfoEntity.class)); if (success) { return R.ok(); @@ -57,9 +78,15 @@ public class PlayClerkTypeInfoController { /** * 修改店员分类信息 */ + @ApiOperation(value = "修改分类", notes = "根据ID修改店员分类信息") + @ApiImplicitParam(name = "id", value = "分类ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "店员分类信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayClerkTypeInfoEntity playClerkTypeInfo) { + public R update(@PathVariable String id, @ApiParam(value = "分类信息", required = true) @RequestBody PlayClerkTypeInfoEntity playClerkTypeInfo) { playClerkTypeInfo.setId(id); boolean success = playClerkTypeInfoService.update(playClerkTypeInfo); if (success) { @@ -71,6 +98,11 @@ public class PlayClerkTypeInfoController { /** * 删除店员分类信息 */ + @ApiOperation(value = "删除分类", notes = "根据ID批量删除店员分类信息") + @ApiImplicitParam(name = "ids", value = "分类ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "店员分类信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserInfoController.java index 91d7819..5e2edcb 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserInfoController.java @@ -17,6 +17,13 @@ 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.ApiImplicitParams; +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.*; @@ -29,6 +36,7 @@ import java.util.List; * @author admin * @since 2024-03-30 */ +@Api(tags = "店员管理", description = "店员信息管理相关接口，包括店员的增删改查、分类、分组以及状态管理等功能") @RestController @RequestMapping("/clerk/user") public class PlayClerkUserInfoController { @@ -41,8 +49,12 @@ public class PlayClerkUserInfoController { /** * 查询店员列表 */ + @ApiOperation(value = "分页查询店员列表", notes = "根据条件分页查询店员列表信息，支持多种筛选条件") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserReturnVo.class, responseContainer = "Page") + }) @PostMapping("listByPage") - public R listByPage(@Validated @RequestBody PlayClerkUserQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkUserQueryVo vo) { IPage list = playClerkUserInfoService.selectByPage(vo); return R.ok(list); } @@ -50,6 +62,11 @@ public class PlayClerkUserInfoController { /** * 按照店员分类查询店员列表 */ + @ApiOperation(value = "按分类查询店员列表", notes = "根据店员分类ID查询所有属于该分类的店员列表") + @ApiImplicitParam(name = "id", value = "店员分类ID", required = true, paramType = "query", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserInfoEntity.class, responseContainer = "List") + }) @GetMapping("listAllByTypeId") public R listAllByTypeId(@RequestParam("id") String id) { List list = playClerkUserInfoService.listAllByTypeId(id); @@ -59,6 +76,11 @@ public class PlayClerkUserInfoController { /** * 按照店员分组查询店员列表 */ + @ApiOperation(value = "按分组查询店员列表", notes = "根据店员分组ID查询所有属于该分组的店员列表") + @ApiImplicitParam(name = "id", value = "店员分组ID", required = true, paramType = "query", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserInfoEntity.class, responseContainer = "List") + }) @GetMapping("listAllByGroupId") public R listAllByGroupId(@RequestParam("id") String id) { List list = playClerkUserInfoService.listAllByGroupId(id); @@ -68,8 +90,12 @@ public class PlayClerkUserInfoController { /** * 修改店员分类 */ + @ApiOperation(value = "修改店员分类", notes = "将指定店员分配到指定分类中，会先清空该分类下所有店员，再重新分配") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class) + }) @PostMapping("editClerkType") - public R listByPage(@Validated @RequestBody PlayClerkUserTypeEditVo vo) { + public R listByPage(@ApiParam(value = "店员分类修改参数", required = true) @Validated @RequestBody PlayClerkUserTypeEditVo vo) { //先清空当前分类下店员 List list = playClerkUserInfoService.listAllByTypeId(vo.getTypeId()); for (PlayClerkUserInfoEntity clerkUserInfo : list) { @@ -93,8 +119,12 @@ public class PlayClerkUserInfoController { * 1、修改店员分组 * 2、将对应账号角色ID设为组长 */ + @ApiOperation(value = "修改店员分组", notes = "将指定店员分配到指定分组中，会先清空该分组下所有店员，再重新分配，并可设置组长") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class) + }) @PostMapping("editClerkGroup") - public R editClerkGroup(@Validated @RequestBody PlayClerkUserTypeEditVo vo) { + public R editClerkGroup(@ApiParam(value = "店员分组修改参数", required = true) @Validated @RequestBody PlayClerkUserTypeEditVo vo) { //先清空当前分类下店员 List list = playClerkUserInfoService.listAllByGroupId(vo.getTypeId()); for (PlayClerkUserInfoEntity clerkUserInfo : list) { @@ -114,7 +144,10 @@ public class PlayClerkUserInfoController { return R.ok("成功"); } - + @ApiOperation(value = "获取简单列表", notes = "获取店员和客户的简单列表信息，用于下拉选择等场景") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = JSONObject.class) + }) @GetMapping("/simple/list") public R simpleList() { List clerkList = playClerkUserInfoService.simpleList(); @@ -126,8 +159,12 @@ public class PlayClerkUserInfoController { /** * 查询店员列表 */ + @ApiOperation(value = "查询店员列表", notes = "分页查询店员信息列表，支持多种条件筛选，返回详细的店员信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserInfoResultVo.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayClerkUserInfoQueryVo vo) { + public R list(@ApiParam(value = "查询条件") PlayClerkUserInfoQueryVo vo) { IPage list = playClerkUserInfoService.selectPlayClerkUserInfoByPage(vo); return R.ok(list); } @@ -135,6 +172,11 @@ public class PlayClerkUserInfoController { /** * 获取店员详细信息 */ + @ApiOperation(value = "获取店员详情", notes = "根据店员ID获取店员的详细信息") + @ApiImplicitParam(name = "id", value = "店员ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkUserInfoService.selectById(id)); @@ -183,8 +225,13 @@ public class PlayClerkUserInfoController { */ //@PreAuthorize("@customSs.hasPermission('clerk:user:update')") @Log(title = "店员", businessType = BusinessType.UPDATE) + @ApiOperation(value = "修改店员信息", notes = "修改店员的基本信息，如昵称、头像、签名等") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PostMapping(value = "/update") - public R update(@Validated @RequestBody PlayClerkUserEditVo vo) { + public R update(@ApiParam(value = "店员信息", required = true) @Validated @RequestBody PlayClerkUserEditVo vo) { PlayClerkUserInfoEntity entity = ConvertUtil.entityToVo(vo, PlayClerkUserInfoEntity.class); boolean success = playClerkUserInfoService.update(entity); if (success) { @@ -199,8 +246,13 @@ public class PlayClerkUserInfoController { */ //@PreAuthorize("@customSs.hasPermission('clerk:user:update')") @Log(title = "店员", businessType = BusinessType.UPDATE) - @PostMapping(value = "/updateState") - public R updateState(@Validated @RequestBody PlayClerkUserStateEditVo vo) { + @ApiOperation(value = "修改店员状态", notes = "修改店员的状态信息，如上下架状态、推荐状态、在线状态等") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) + @PostMapping(value = "/update/state") + public R updateState(@ApiParam(value = "店员状态信息", required = true) @Validated @RequestBody PlayClerkUserStateEditVo vo) { PlayClerkUserInfoEntity entity = ConvertUtil.entityToVo(vo, PlayClerkUserInfoEntity.class); boolean success = playClerkUserInfoService.update(entity); if (success) { @@ -212,8 +264,13 @@ public class PlayClerkUserInfoController { /** * 删除店员 */ - //@PreAuthorize("@customSs.hasPermission('clerk:user:delete')") + //@PreAuthorize("@customSs.hasPermission('clerk:user:remove')") @Log(title = "店员", businessType = BusinessType.DELETE) + @ApiOperation(value = "删除店员", notes = "根据ID批量删除店员信息") + @ApiImplicitParam(name = "ids", value = "店员ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { return R.ok(playClerkUserInfoService.deletePlayClerkUserInfoByIds(ids)); diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserReviewInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserReviewInfoController.java index d2a1d84..fd401b3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserReviewInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkUserReviewInfoController.java @@ -8,6 +8,13 @@ import com.starry.admin.modules.clerk.service.IPlayClerkUserReviewInfoService; 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.ApiImplicitParams; +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.*; @@ -19,6 +26,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-19 */ +@Api(tags = "店员资料审核", description = "店员资料审核相关接口，包括审核列表查询、审核状态修改和删除等操作") @RestController @RequestMapping("/clerk/user/review") public class PlayClerkUserReviewInfoController { @@ -28,8 +36,12 @@ public class PlayClerkUserReviewInfoController { /** * 查询店员资料审核列表 */ + @ApiOperation(value = "查询审核列表", notes = "分页查询店员资料审核列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserReviewReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayClerkUserReviewQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkUserReviewQueryVo vo) { IPage list = playClerkUserReviewInfoService.selectByPage(vo); return R.ok(list); } @@ -37,10 +49,14 @@ public class PlayClerkUserReviewInfoController { /** * 修改店员资料审核 */ + @ApiOperation(value = "修改审核状态", notes = "更新店员资料审核状态，通过或拒绝") + @ApiResponses({ + @ApiResponse(code = 200, message = "修改成功") + }) //@PreAuthorize("@customSs.hasPermission('clerk:userReview:update')") @Log(title = "店员资料审核", businessType = BusinessType.UPDATE) @PostMapping(value = "/update") - public R update(@Validated @RequestBody PlayClerkUserReviewStateEditVo vo) { + public R update(@ApiParam(value = "审核状态信息", required = true) @Validated @RequestBody PlayClerkUserReviewStateEditVo vo) { playClerkUserReviewInfoService.updateDataReviewState(vo); return R.ok("修改成功"); } @@ -48,6 +64,11 @@ public class PlayClerkUserReviewInfoController { /** * 删除店员资料审核 */ + @ApiOperation(value = "删除审核记录", notes = "根据ID批量删除店员资料审核记录") + @ApiImplicitParam(name = "ids", value = "审核记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) //@PreAuthorize("@customSs.hasPermission('clerk:userReview:delete')") @Log(title = "店员资料审核", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesDetailsInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesDetailsInfoController.java index 41452ab..db7605f 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesDetailsInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesDetailsInfoController.java @@ -6,6 +6,13 @@ import com.starry.admin.modules.clerk.service.IPlayClerkWagesDetailsInfoService; 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.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; @@ -16,6 +23,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-31 */ +@Api(tags = "店员工资明细", description = "店员工资明细信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/wages/details") public class PlayClerkWagesDetailsInfoController { @@ -25,8 +33,12 @@ public class PlayClerkWagesDetailsInfoController { /** * 查询店员工资明细信息列表 */ + @ApiOperation(value = "查询工资明细列表", notes = "分页查询店员工资明细信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkWagesDetailsInfoEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayClerkWagesDetailsInfoEntity playClerkWagesDetailsInfo) { + public R list(@ApiParam(value = "查询条件") PlayClerkWagesDetailsInfoEntity playClerkWagesDetailsInfo) { IPage list = playClerkWagesDetailsInfoService.selectPlayClerkWagesDetailsInfoByPage(playClerkWagesDetailsInfo); return R.ok(list); } @@ -34,6 +46,11 @@ public class PlayClerkWagesDetailsInfoController { /** * 获取店员工资明细信息详细信息 */ + @ApiOperation(value = "获取工资明细详情", notes = "根据ID获取店员工资明细详细信息") + @ApiImplicitParam(name = "id", value = "工资明细ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkWagesDetailsInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkWagesDetailsInfoService.selectPlayClerkWagesDetailsInfoById(id)); @@ -42,9 +59,14 @@ public class PlayClerkWagesDetailsInfoController { /** * 新增店员工资明细信息 */ + @ApiOperation(value = "新增工资明细", notes = "创建新的店员工资明细记录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "店员工资明细信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayClerkWagesDetailsInfoEntity playClerkWagesDetailsInfo) { + public R create(@ApiParam(value = "工资明细信息", required = true) @RequestBody PlayClerkWagesDetailsInfoEntity playClerkWagesDetailsInfo) { boolean success = playClerkWagesDetailsInfoService.create(playClerkWagesDetailsInfo); if (success) { return R.ok(); @@ -55,9 +77,15 @@ public class PlayClerkWagesDetailsInfoController { /** * 修改店员工资明细信息 */ + @ApiOperation(value = "修改工资明细", notes = "根据ID修改店员工资明细信息") + @ApiImplicitParam(name = "id", value = "工资明细ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "店员工资明细信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayClerkWagesDetailsInfoEntity playClerkWagesDetailsInfo) { + public R update(@PathVariable String id, @ApiParam(value = "工资明细信息", required = true) @RequestBody PlayClerkWagesDetailsInfoEntity playClerkWagesDetailsInfo) { playClerkWagesDetailsInfo.setId(id); boolean success = playClerkWagesDetailsInfoService.update(playClerkWagesDetailsInfo); if (success) { @@ -69,6 +97,11 @@ public class PlayClerkWagesDetailsInfoController { /** * 删除店员工资明细信息 */ + @ApiOperation(value = "删除工资明细", notes = "根据ID批量删除店员工资明细信息") + @ApiImplicitParam(name = "ids", value = "工资明细ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "店员工资明细信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesInfoController.java index 44e9c8b..5f36606 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayClerkWagesInfoController.java @@ -14,6 +14,13 @@ import com.starry.admin.modules.order.module.entity.PlayOrderInfoEntity; import com.starry.admin.modules.weichat.entity.wages.ClerkWagesDetailsReturnVo; 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.ApiImplicitParams; +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 +35,7 @@ import java.util.List; * @author admin * @since 2024-05-31 */ +@Api(tags = "店员工资结算", description = "店员工资结算信息管理相关接口，包括查询历史工资、未结算工资和工资明细等") @RestController @RequestMapping("/clerk/wages") public class PlayClerkWagesInfoController { @@ -43,16 +51,24 @@ public class PlayClerkWagesInfoController { /** * 查询店员工资结算信息列表 */ + @ApiOperation(value = "查询历史工资列表", notes = "分页查询店员历史工资结算信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Object.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayClerkWagesInfoQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkWagesInfoQueryVo vo) { return R.ok(playClerkWagesInfoService.selectHistoricalByPage(vo)); } /** * 查询店员工未结算工资 */ + @ApiOperation(value = "查询未结算工资", notes = "分页查询店员未结算工资信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUnsettledWagesInfoReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listUnsettledWagesByPage") - public R list(@Validated @RequestBody PlayClerkUnsettledWagesInfoQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkUnsettledWagesInfoQueryVo vo) { IPage page = playClerkUserInfoService.listUnsettledWagesByPage(vo); for (PlayClerkUnsettledWagesInfoReturnVo record : page.getRecords()) { Integer orderState1Number = 0; @@ -90,6 +106,12 @@ public class PlayClerkWagesInfoController { } + @ApiOperation(value = "查询工资明细", notes = "根据工资结算ID查询工资明细信息") + @ApiImplicitParam(name = "id", value = "工资结算ID", required = true, paramType = "query", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = ClerkWagesDetailsReturnVo.class, responseContainer = "List"), + @ApiResponse(code = 500, message = "ID不能为空") + }) @GetMapping("queryWagesDetailsById") public R clerkQueryWagesDetails(@RequestParam("id") String id) { if (StrUtil.isBlankIfStr(id)) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayCustomArticleInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayCustomArticleInfoController.java index c36423d..1f63e03 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayCustomArticleInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/controller/PlayCustomArticleInfoController.java @@ -6,6 +6,13 @@ import com.starry.admin.modules.clerk.service.IPlayCustomArticleInfoService; 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.ApiImplicitParams; +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.web.bind.annotation.*; @@ -17,6 +24,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-04 */ +@Api(tags = "陪聊动态管理", description = "陪聊点赞动态信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/custom/article") public class PlayCustomArticleInfoController { @@ -26,8 +34,12 @@ public class PlayCustomArticleInfoController { /** * 查询陪聊点赞动态信息列表 */ + @ApiOperation(value = "查询动态列表", notes = "分页查询陪聊点赞动态信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomArticleInfoEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayCustomArticleInfoEntity playCustomArticleInfo) { + public R list(@ApiParam(value = "查询条件") PlayCustomArticleInfoEntity playCustomArticleInfo) { IPage list = playCustomArticleInfoService.selectPlayCustomArticleInfoByPage(playCustomArticleInfo); return R.ok(list); } @@ -35,6 +47,11 @@ public class PlayCustomArticleInfoController { /** * 获取陪聊点赞动态信息详细信息 */ + @ApiOperation(value = "获取动态详情", notes = "根据ID获取陪聊点赞动态详细信息") + @ApiImplicitParam(name = "id", value = "动态ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomArticleInfoEntity.class) + }) @PreAuthorize("@customSs.hasPermission('play:info:query')") @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { @@ -44,10 +61,15 @@ public class PlayCustomArticleInfoController { /** * 新增陪聊点赞动态信息 */ + @ApiOperation(value = "新增动态", notes = "创建新的陪聊点赞动态信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @PreAuthorize("@customSs.hasPermission('play:info:create')") @Log(title = "陪聊点赞动态信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCustomArticleInfoEntity playCustomArticleInfo) { + public R create(@ApiParam(value = "动态信息", required = true) @RequestBody PlayCustomArticleInfoEntity playCustomArticleInfo) { boolean success = playCustomArticleInfoService.create(playCustomArticleInfo); if (success) { return R.ok(); @@ -58,10 +80,16 @@ public class PlayCustomArticleInfoController { /** * 修改陪聊点赞动态信息 */ + @ApiOperation(value = "修改动态", notes = "根据ID修改陪聊点赞动态信息") + @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('play:info:edit')") @Log(title = "陪聊点赞动态信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCustomArticleInfoEntity playCustomArticleInfo) { + public R update(@PathVariable String id, @ApiParam(value = "动态信息", required = true) @RequestBody PlayCustomArticleInfoEntity playCustomArticleInfo) { playCustomArticleInfo.setId(id); boolean success = playCustomArticleInfoService.update(playCustomArticleInfo); if (success) { @@ -73,6 +101,11 @@ public class PlayCustomArticleInfoController { /** * 删除陪聊点赞动态信息 */ + @ApiOperation(value = "删除动态", notes = "根据ID批量删除陪聊点赞动态信息") + @ApiImplicitParam(name = "ids", value = "动态ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @PreAuthorize("@customSs.hasPermission('play:info:remove')") @Log(title = "陪聊点赞动态信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserQueryVo.java index d22f3b8..3835a19 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.module.entity; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,119 +16,142 @@ import java.util.List; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "店员分页查询参数", description = "分页查询店员列表的条件参数") public class PlayClerkUserQueryVo extends BasePageEntity { /** * UUID */ + @ApiModelProperty(value = "店员ID", notes = "唯一标识") private String id; /** * 昵称 */ + @ApiModelProperty(value = "店员昵称", notes = "支持模糊查询") private String nickname; /** * 电话号码 */ + @ApiModelProperty(value = "电话号码") private String phone; /** * 分组ID */ + @ApiModelProperty(value = "分组ID") private String groupId; /** * 性别[0:未知;1:男;2:女] */ + @ApiModelProperty(value = "性别", notes = "0:未知;1:男;2:女") private String sex; /** * 是否固定等级(0:固定等级，1:不固定) */ + @ApiModelProperty(value = "是否固定等级", notes = "0:固定等级，1:不固定") private String fixingLevel; /** * 店员等级 */ + @ApiModelProperty(value = "店员等级ID") private String levelId; /** * 年龄 */ + @ApiModelProperty(value = "年龄范围", notes = "年龄区间查询，如[18, 25]") private List ages; /** * 所在国家 */ + @ApiModelProperty(value = "所在国家", example = "中国") private String country; /** * 所在省份 */ + @ApiModelProperty(value = "所在省份", example = "广东省") private String province; /** * 所在城市 */ + @ApiModelProperty(value = "所在城市", example = "深圳市") private String city; /** * 在职状态（1：在职，0：离职） */ + @ApiModelProperty(value = "在职状态", notes = "1：在职，0：离职", example = "1") private String onboardingState = "1"; /** * 是否推荐状态（1：已推荐，0：未推荐） */ + @ApiModelProperty(value = "是否推荐", notes = "1：已推荐，0：未推荐") private String recommendationState; /** * 是否置顶状态（1：已置顶，0：未置顶） */ + @ApiModelProperty(value = "是否置顶", notes = "1：已置顶，0：未置顶") private String pinToTopState; /** * 在线状态【1：在线，0：离线】 */ + @ApiModelProperty(value = "在线状态", notes = "1：在线，0：离线") private String onlineState; /** * 上架状态【1：上架，0：下架】 */ + @ApiModelProperty(value = "上架状态", notes = "1：上架，0：下架") private String listingState; /** * 显示状态【1：显示，0：隐藏】 */ + @ApiModelProperty(value = "显示状态", notes = "1：显示，0：隐藏") private String displayState; /** * 实名状态【1：已实名，0：未实名】 */ + @ApiModelProperty(value = "实名状态", notes = "1：已实名，0：未实名") private String realState; /** * 是否必须实名【0:非必须实名;1:必须实名;2:跟随店铺设置】 */ + @ApiModelProperty(value = "是否必须实名", notes = "0:非必须实名;1:必须实名;2:跟随店铺设置") private String mandatoryRealState; /** * 随机接单状态【1：允许，0：禁止】 */ + @ApiModelProperty(value = "随机接单状态", notes = "1：允许，0：禁止") private String randomOrderState; /** * 店员状态（0:不是陪聊，1:陪聊，2:资料审核中） */ + @ApiModelProperty(value = "店员状态", notes = "0:不是陪聊，1:陪聊，2:资料审核中", example = "1") private String clerkState = "1"; /** * 身份证号 */ + @ApiModelProperty(value = "身份证号") private String code; diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserReturnVo.java index 13ead76..65e4c79 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserReturnVo.java @@ -3,6 +3,8 @@ package com.starry.admin.modules.clerk.module.entity; import com.fasterxml.jackson.annotation.JsonFormat; import com.fasterxml.jackson.annotation.JsonIgnore; import com.starry.admin.modules.order.module.entity.PlayOrderInfoEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import org.springframework.format.annotation.DateTimeFormat; @@ -18,150 +20,179 @@ import java.util.List; * @since 2024-03-30 */ @Data +@ApiModel(value = "店员详细信息返回对象", description = "分页查询店员详细信息的返回结果") public class PlayClerkUserReturnVo { /** * UUID */ + @ApiModelProperty(value = "店员ID", notes = "唯一标识") private String id; /** * 店员昵称 */ + @ApiModelProperty(value = "店员昵称") private String nickname; /** * 店员等级 */ + @ApiModelProperty(value = "店员等级ID") private String levelId; /** * 店员等级 */ + @ApiModelProperty(value = "店员等级名称") private String levelName; /** * 分组ID */ + @ApiModelProperty(value = "分组ID") private String groupId; /** * 分组ID */ + @ApiModelProperty(value = "分组名称") private String groupName; /** * 性别[0:未知;1:男;2:女] */ + @ApiModelProperty(value = "性别", notes = "0:未知;1:男;2:女") private String sex; /** * 头像 */ + @ApiModelProperty(value = "头像", notes = "头像图片URL") private String avatar; /** * 音频 */ + @ApiModelProperty(value = "音频", notes = "音频文件URL") private String audio; /** * 星座 */ + @ApiModelProperty(value = "星座", example = "天蝎座") private String constellation; /** * 标签 */ + @ApiModelProperty(value = "标签列表", notes = "店员个人标签") private List label = new ArrayList<>(); /** * 相册 */ + @ApiModelProperty(value = "相册列表", notes = "店员相册图片URL列表") private List album = new ArrayList<>(); /** * 个性签名 */ + @ApiModelProperty(value = "个性签名") private String signature; /** * 年龄 */ + @ApiModelProperty(value = "年龄", example = "25") private Integer age; /** * 所在省份 */ + @ApiModelProperty(value = "所在省份", example = "广东省") private String province; /** * 所在城市 */ + @ApiModelProperty(value = "所在城市", example = "深圳市") private String city; /** * 在线状态【1：在线，0：离线】 */ + @ApiModelProperty(value = "在线状态", notes = "1：在线，0：离线") private String onlineState; /** * 上架状态【1：上架，0：下架】 */ + @ApiModelProperty(value = "上架状态", notes = "1：上架，0：下架") private String listingState; /** * 实名状态【1：已实名，0：未实名】 */ + @ApiModelProperty(value = "实名状态", notes = "1：已实名，0：未实名") private String realState; /** * 是否必须实名【0:非必须实名;1:必须实名;2:跟随店铺设置】 */ + @ApiModelProperty(value = "是否必须实名", notes = "0:非必须实名;1:必须实名;2:跟随店铺设置") private String mandatoryRealState; /** * 随机接单状态【1：允许，0：禁止】 */ + @ApiModelProperty(value = "随机接单状态", notes = "1：允许，0：禁止") private String randomOrderState; /** * 地址 */ + @ApiModelProperty(value = "地址", notes = "店员所在详细地址") private String address; /** * 地址 */ + @ApiModelProperty(value = "备注") private String remark; /** * 订单列表 */ @JsonIgnore + @ApiModelProperty(value = "订单列表", hidden = true) private List orderInfos; /** * 订单总数 */ + @ApiModelProperty(value = "订单总数") private String orderNumber; /** * 续单总数 */ + @ApiModelProperty(value = "续单总数") private String orderContinueNumber; /** * 订单总金额 */ + @ApiModelProperty(value = "订单总金额") private BigDecimal orderTotalAmount; @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; @@ -170,6 +201,7 @@ public class PlayClerkUserReturnVo { */ @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") + @ApiModelProperty(value = "入职时间", example = "2024-01-01") private LocalDateTime entryTime; /** @@ -177,38 +209,45 @@ public class PlayClerkUserReturnVo { */ @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8") + @ApiModelProperty(value = "离职时间", example = "2024-01-01") private LocalDateTime resignationTime; /** * 是否推荐状态（1：已推荐，0：未推荐） */ + @ApiModelProperty(value = "是否推荐", notes = "1：已推荐，0：未推荐") private String recommendationState; /** * 是否置顶状态（1：已置顶，0：未置顶） */ + @ApiModelProperty(value = "是否置顶", notes = "1：已置顶，0：未置顶") private String pinToTopState; /** * 显示状态【1：显示，0：隐藏】 */ + @ApiModelProperty(value = "显示状态", notes = "1：显示，0：隐藏") private String displayState; /** * 是否固定等级(0:固定等级，1:不固定) */ + @ApiModelProperty(value = "是否固定等级", notes = "0:固定等级，1:不固定") private String fixingLevel; /** * 在职状态（1：在职，0：离职） */ + @ApiModelProperty(value = "在职状态", notes = "1：在职，0：离职") private String onboardingState; /** * 在职天数 */ + @ApiModelProperty(value = "在职天数", example = "365") private Integer workingHours = 0; diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserTypeEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserTypeEditVo.java index be5631e..21712ff 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserTypeEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/entity/PlayClerkUserTypeEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.entity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotNull; @@ -12,6 +14,7 @@ import java.util.List; * @since 2024-03-30 */ @Data +@ApiModel(value = "店员分类编辑对象", description = "修改店员分类或分组的参数对象") public class PlayClerkUserTypeEditVo { @@ -19,12 +22,14 @@ public class PlayClerkUserTypeEditVo { * 店员分类ID */ @NotNull(message = "类型不能为空") + @ApiModelProperty(value = "店员分类/分组ID", required = true, notes = "分类ID或分组ID") private String typeId; /** * 店员列表 */ @NotNull(message = "店员列表不能为空") + @ApiModelProperty(value = "店员ID列表", required = true, notes = "要添加到分类/分组中的店员ID列表") private List clerkUserIds; diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoAddVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoAddVo.java index c4c9b8f..e72939f 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoAddVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoAddVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.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; @@ -12,6 +14,7 @@ import java.time.LocalDateTime; * @since 2024/6/6 下午11:13 **/ @Data +@ApiModel(value = "店员头像框添加参数", description = "新增店员头像框信息的请求参数") public class PlayAvatarFrameInfoAddVo { /** @@ -19,33 +22,40 @@ public class PlayAvatarFrameInfoAddVo { */ @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") + @ApiModelProperty(value = "添加时间", hidden = true, notes = "系统自动生成，无需传入") private final LocalDateTime addTime = LocalDateTime.now(); /** * 头像框名称 */ @NotNull(message = "头像框名称不能为空") + @ApiModelProperty(value = "头像框名称", required = true, example = "年度贡献者", notes = "头像框的名称") private String avatarFrameName; /** * 头像框地址 */ @NotNull(message = "头像框图片不能为空") + @ApiModelProperty(value = "头像框地址", required = true, example = "https://example.com/frame.png", notes = "头像框图片的URL地址") private String avatarFrameAddress; /** * 获取方式(0:手动赠送;1:自动赠送) */ @NotNull(message = "头像框获取方式不能为空") + @ApiModelProperty(value = "获取方式", required = true, example = "0", notes = "0:手动赠送;1:自动赠送") private String accessType; /** * 获取条件名称 */ + @ApiModelProperty(value = "获取条件名称", example = "年度贡献奖", notes = "获取该头像框的条件名称") private String accessName; /** * 获取条件 */ + @ApiModelProperty(value = "获取条件", example = "年度贡献超过10000元", notes = "获取该头像框的具体条件") private String accessValue; /** * 有效期（单位：天，-1:永久有效） */ @NotNull(message = "有效期不能为空") + @ApiModelProperty(value = "有效期", required = true, example = "365", notes = "头像框的有效期，单位：天，-1表示永久有效") private String periodValidity; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoQueryVo.java index 75dd7d2..a2c12f7 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameInfoQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -10,6 +12,7 @@ import lombok.EqualsAndHashCode; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "店员头像框查询参数", description = "查询店员头像框信息的条件参数") public class PlayAvatarFrameInfoQueryVo extends BasePageEntity { } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameSendVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameSendVo.java index 72f5a6f..3b3676c 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameSendVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayAvatarFrameSendVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotNull; @@ -9,12 +11,15 @@ import javax.validation.constraints.NotNull; * @since 2024/6/6 下午11:13 **/ @Data +@ApiModel(value = "店员头像框赠送参数", description = "赠送头像框给店员的请求参数") public class PlayAvatarFrameSendVo { + @ApiModelProperty(value = "店员ID", required = true, example = "1", notes = "接收头像框的店员ID") private String clerkId; @NotNull(message = "头像框获取方式不能为空") + @ApiModelProperty(value = "头像框ID", required = true, example = "1", notes = "要赠送的头像框ID") private String avatarFrameId; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleQueryVo.java index 931f088..1322bba 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.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,28 +14,34 @@ import java.util.List; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "店员动态查询参数", description = "查询店员动态信息的条件参数") public class PlayClerkArticleQueryVo extends BasePageEntity { + @ApiModelProperty(value = "动态ID", example = "1", notes = "特定动态的ID") private String id; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "特定店员的ID") private String clerkId; /** * 审核状态（0：未审核:1：审核通过，2：审核不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0：未审核:1：审核通过，2：审核不通过") private String reviewState; /** * 发布时间 */ + @ApiModelProperty(value = "发布时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "动态发布时间范围，包含开始和结束时间") private List releaseTime; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1", notes = "特定顾客的ID") private String customId; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReturnVo.java index f838904..1d28af2 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReturnVo.java @@ -3,6 +3,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.fasterxml.jackson.annotation.JsonFormat; import com.fasterxml.jackson.annotation.JsonIgnore; import com.starry.admin.modules.clerk.module.entity.PlayCustomArticleInfoEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import org.springframework.format.annotation.DateTimeFormat; @@ -14,41 +16,49 @@ import java.util.List; * 动态信息查询返回对象 */ @Data +@ApiModel(value = "店员动态返回数据", description = "店员动态信息的返回数据") public class PlayClerkArticleReturnVo { /** * UUID */ + @ApiModelProperty(value = "动态ID", example = "1") private String id; /** * 陪聊用户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 = "动态内容", example = "今天天气真好，感谢大家的支持！") private String articleCon; /** * 动态附件类型（0:图片;1:视频;2:音频） */ + @ApiModelProperty(value = "附件类型", example = "0", notes = "0:图片;1:视频;2:音频") private String annexType; /** * 动态附件内容 */ + @ApiModelProperty(value = "附件内容", example = "[\"https://example.com/photo1.jpg\"]", notes = "附件内容，根据附件类型有不同格式") private List annexCon; @@ -57,26 +67,31 @@ public class PlayClerkArticleReturnVo { */ @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 releaseTime; /** * 备注(审核理由) */ + @ApiModelProperty(value = "审核理由", example = "内容健康，通过审核") private String reviewCon; /** * 点赞人数 */ + @ApiModelProperty(value = "点赞人数", example = "10") private Integer agreedQuantity = 0; /** * 审核状态（0：未审核:1：审核通过，2：审核不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0：未审核:1：审核通过，2：审核不通过") private String reviewState; /** * 陪聊点赞动态 */ @JsonIgnore + @ApiModelProperty(value = "点赞动态", hidden = true) private List articleInfoEntities; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReviewStateEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReviewStateEditVo.java index 610d90e..51d215c 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReviewStateEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkArticleReviewStateEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -11,10 +13,12 @@ import java.time.LocalDateTime; * 动态审核 */ @Data +@ApiModel(value = "店员动态审核状态修改参数", description = "修改店员动态审核状态的请求参数") public class PlayClerkArticleReviewStateEditVo { @NotBlank(message = "ID不能为空") + @ApiModelProperty(value = "动态ID", required = true, example = "1", notes = "店员动态的ID") private String id; /** @@ -22,15 +26,18 @@ public class PlayClerkArticleReviewStateEditVo { */ @NotBlank(message = "审核状态不能为空") @Pattern(regexp = "[12]", message = "审核状态必须为1或2") + @ApiModelProperty(value = "审核状态", required = true, example = "1", notes = "1：审核通过，2：审核不通过") private String reviewState; /** * 发布时间 */ + @ApiModelProperty(value = "备注", example = "内容健康，通过审核", notes = "审核的备注内容或拒绝原因") private String remark; /** * 审核时间 */ + @ApiModelProperty(value = "审核时间", hidden = true, notes = "系统自动生成，无需传入") private LocalDateTime reviewTime = LocalDateTime.now(); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkCommodityQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkCommodityQueryVo.java index 57d6de4..bd6ca95 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkCommodityQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkCommodityQueryVo.java @@ -1,16 +1,20 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; /** * @author admin */ @Data +@ApiModel(value = "陪聊服务项目查询参数", description = "查询陪聊服务项目的条件参数") public class PlayClerkCommodityQueryVo { /** * 项目类型 */ + @ApiModelProperty(value = "项目类型", example = "1", notes = "服务项目的类型") private String commodityType; @@ -19,6 +23,7 @@ public class PlayClerkCommodityQueryVo { * 0:停用 * 1:启用 */ + @ApiModelProperty(value = "启用状态", example = "1", notes = "0:停用,1:启用") private String enablingState; public PlayClerkCommodityQueryVo(String commodityType, String enablingState) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewQueryVo.java index 9655395..d18cfd4 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,25 +16,30 @@ import java.util.List; */ @Data @EqualsAndHashCode(callSuper = false) +@ApiModel(value = "店员资料内容审核查询参数", description = "查询店员资料内容审核信息的条件参数") public class PlayClerkDataReviewQueryVo extends BasePageEntity { /** * UUID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "特定店员的ID") private String clerkId; /** * 资料类型[0:昵称;1:头像;2:相册;3:录音] */ + @ApiModelProperty(value = "资料类型", example = "1", notes = "0:昵称;1:头像;2:相册;3:录音") private String dataType; /** * 审核状态（0：未审核:1：审核通过，2：审核不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0：未审核:1：审核通过，2：审核不通过") private String reviewState; /** * 资料添加时间 */ + @ApiModelProperty(value = "添加时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "资料添加时间范围，包含开始和结束时间") private List addTime; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewReturnVo.java index 3ea5839..00b9e49 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewReturnVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.time.LocalDateTime; @@ -12,69 +14,82 @@ import java.util.List; * @since 2024-05-19 */ @Data +@ApiModel(value = "店员资料内容审核返回数据", description = "店员资料内容审核信息的返回数据") public class PlayClerkDataReviewReturnVo { /** * UUID */ + @ApiModelProperty(value = "审核记录ID", example = "1") private String id; /** * 店员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; /** * 资料类型[0:昵称;1:头像;2:相册;3:录音] */ + @ApiModelProperty(value = "资料类型", example = "1", notes = "0:昵称;1:头像;2:相册;3:录音") private String dataType; /** * 资料内容 */ + @ApiModelProperty(value = "资料内容", example = "[\"https://example.com/photo1.jpg\"]", notes = "资料内容，根据资料类型有不同格式") private List dataContent; /** * 审核状态（0：未审核:1：审核通过，2：审核不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0：未审核:1：审核通过，2：审核不通过") private String reviewState; /** * 资料添加时间 */ + @ApiModelProperty(value = "添加时间", example = "2024-01-01 12:00:00") private LocalDateTime addTime; /** * 审核时间 */ + @ApiModelProperty(value = "审核时间", example = "2024-01-02 12:00:00") private LocalDateTime reviewTime; /** * 审核人 */ + @ApiModelProperty(value = "审核人", example = "admin") private String reviewBy; /** * 审核内容 */ + @ApiModelProperty(value = "审核内容", example = "资料完整，通过审核") private String reviewCon; /** * 备注 */ + @ApiModelProperty(value = "备注", example = "资料清晰可见") private String remark; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewStateEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewStateEditVo.java index feb6852..afe93a7 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewStateEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkDataReviewStateEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -11,10 +13,12 @@ import java.time.LocalDateTime; * 动态审核 */ @Data +@ApiModel(value = "店员资料审核状态修改参数", description = "修改店员资料审核状态的请求参数") public class PlayClerkDataReviewStateEditVo { @NotBlank(message = "ID不能为空") + @ApiModelProperty(value = "审核记录ID", required = true, example = "1", notes = "店员资料审核记录的ID") private String id; /** @@ -22,15 +26,18 @@ public class PlayClerkDataReviewStateEditVo { */ @NotBlank(message = "审核状态不能为空") @Pattern(regexp = "[12]", message = "审核状态必须为1或2") + @ApiModelProperty(value = "审核状态", required = true, example = "1", notes = "1：审核通过，2：审核不通过") private String reviewState; /** * 审核内容 */ + @ApiModelProperty(value = "审核内容", example = "资料完整，通过审核", notes = "审核的备注内容或拒绝原因") private String reviewCon; /** * 审核时间 */ + @ApiModelProperty(value = "审核时间", hidden = true, notes = "系统自动生成，无需传入") private LocalDateTime reviewTime = LocalDateTime.now(); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelAddVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelAddVo.java index 5ce7130..b709b82 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelAddVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelAddVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -8,42 +10,50 @@ import javax.validation.constraints.NotBlank; * @author admin */ @Data +@ApiModel(value = "店员等级添加参数", description = "新增店员等级信息的请求参数") public class PlayClerkLevelAddVo { /** * 等级名称 */ @NotBlank(message = "等级名称不能为空") + @ApiModelProperty(value = "等级名称", required = true, example = "高级店员", notes = "店员等级的名称") private String name; /** * 首次固定单比例[0 - 100%] */ + @ApiModelProperty(value = "首次固定单比例", example = "70", notes = "首次固定单提成比例，范围0-100%") private Integer firstRegularRatio; /** * 非首次固定单比例[0 - 100%] */ + @ApiModelProperty(value = "非首次固定单比例", example = "60", notes = "非首次固定单提成比例，范围0-100%") private Integer notFirstRegularRatio; /** * 首次打赏比例[0 - 100%] */ + @ApiModelProperty(value = "首次打赏比例", example = "80", notes = "首次打赏提成比例，范围0-100%") private Integer firstRewardRatio; /** * 非首次打赏比例[0 - 100%] */ + @ApiModelProperty(value = "非首次打赏比例", example = "70", notes = "非首次打赏提成比例，范围0-100%") private Integer notFirstRewardRatio; /** * 首次随机单比例[0 - 100%] */ + @ApiModelProperty(value = "首次随机单比例", example = "75", notes = "首次随机单提成比例，范围0-100%") private Integer firstRandomRadio; /** * 非首次随机单比例[0 - 100%] */ + @ApiModelProperty(value = "非首次随机单比例", example = "65", notes = "非首次随机单提成比例，范围0-100%") private Integer notFirstRandomRadio; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelEditVo.java index 9feabb3..c801421 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkLevelEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -8,53 +10,64 @@ import javax.validation.constraints.NotBlank; * @author admin */ @Data +@ApiModel(value = "店员等级修改参数", description = "修改店员等级信息的请求参数") public class PlayClerkLevelEditVo { /** * 等级名称 */ @NotBlank(message = "ID不能为空") + @ApiModelProperty(value = "等级ID", required = true, example = "1", notes = "店员等级的ID") private String id; /** * 等级名称 */ @NotBlank(message = "等级名称不能为空") + @ApiModelProperty(value = "等级名称", required = true, example = "高级店员", notes = "店员等级的名称") private String name; /** * 首次固定单比例[0 - 100%] */ + @ApiModelProperty(value = "首次固定单比例", example = "70", notes = "首次固定单提成比例，范围0-100%") private Integer firstRegularRatio; /** * 非首次固定单比例[0 - 100%] */ + @ApiModelProperty(value = "非首次固定单比例", example = "60", notes = "非首次固定单提成比例，范围0-100%") private Integer notFirstRegularRatio; /** * 首次打赏比例[0 - 100%] */ + @ApiModelProperty(value = "首次打赏比例", example = "80", notes = "首次打赏提成比例，范围0-100%") private Integer firstRewardRatio; /** * 非首次打赏比例[0 - 100%] */ + @ApiModelProperty(value = "非首次打赏比例", example = "70", notes = "非首次打赏提成比例，范围0-100%") private Integer notFirstRewardRatio; /** * 首次随机单比例[0 - 100%] */ + @ApiModelProperty(value = "首次随机单比例", example = "75", notes = "首次随机单提成比例，范围0-100%") private Integer firstRandomRadio; /** * 非首次随机单比例[0 - 100%] */ + @ApiModelProperty(value = "非首次随机单比例", example = "65", notes = "非首次随机单提成比例，范围0-100%") private Integer notFirstRandomRadio; + @ApiModelProperty(value = "样式类型", example = "1", notes = "等级样式类型") private Integer styleType; - private String styleImageUrl; + @ApiModelProperty(value = "样式图片URL", example = "https://example.com/style.jpg", notes = "等级样式图片URL") + private String styleImageUrl; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoAddVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoAddVo.java index 5965be6..85093de 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoAddVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoAddVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotNull; @@ -9,6 +11,7 @@ import javax.validation.constraints.NotNull; * @since 2024/6/2 下午5:59 **/ @Data +@ApiModel(value = "店员分类添加参数", description = "新增店员分类信息的请求参数") public class PlayClerkTypeInfoAddVo { @@ -16,18 +19,21 @@ public class PlayClerkTypeInfoAddVo { * 分类名称 */ @NotNull(message = "分类名称不能为空") + @ApiModelProperty(value = "分类名称", required = true, example = "新人店员", notes = "店员分类的名称") private String typeName; /** * 是否在首页显示（0:不显示,1:显示） */ @NotNull(message = "是否在首页显示不能为空") + @ApiModelProperty(value = "是否在首页显示", required = true, example = "1", notes = "0:不显示,1:显示") private String homeDisplayed; /** * 排序 */ @NotNull(message = "排序不能为空") + @ApiModelProperty(value = "排序", required = true, example = "1", notes = "数字越小排序越靠前") private Integer sort; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoQueryVo.java index 7b5879a..91a0f26 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkTypeInfoQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -10,8 +12,10 @@ import lombok.EqualsAndHashCode; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "店员分类查询参数", description = "查询店员分类信息的条件参数") public class PlayClerkTypeInfoQueryVo extends BasePageEntity { + @ApiModelProperty(value = "分类ID", example = "1", notes = "店员分类的ID") private String id; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUnsettledWagesInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUnsettledWagesInfoQueryVo.java index 4eb06c2..1909b3d 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUnsettledWagesInfoQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUnsettledWagesInfoQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -10,16 +12,19 @@ import lombok.EqualsAndHashCode; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "未结算工资查询参数", description = "查询店员未结算工资信息的条件参数") public class PlayClerkUnsettledWagesInfoQueryVo extends BasePageEntity { /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "特定店员的ID") private String clerkId; /** * 店员上架状态 */ + @ApiModelProperty(value = "店员上架状态", example = "1", notes = "1：上架，0：下架") private String listingState; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserEditVo.java index c325653..70e44fe 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -10,100 +12,117 @@ import javax.validation.constraints.NotNull; * @author admin */ @Data +@ApiModel(value = "店员编辑对象", description = "修改店员基本信息的参数对象") public class PlayClerkUserEditVo { /** * id */ @NotBlank(message = "id不能为空") + @ApiModelProperty(value = "店员ID", required = true, notes = "唯一标识") private String id; /** * 账号ID */ @NotBlank(message = "账号不能为空") + @ApiModelProperty(value = "账号ID", required = true, notes = "关联的用户账号ID") private String playUserId; /** * 用户的标识，对当前公众号唯一 */ + @ApiModelProperty(value = "微信OpenID", notes = "用户在微信公众号中的唯一标识") private String openid; /** * 店员昵称 */ @NotBlank(message = "昵称不能为空") + @ApiModelProperty(value = "店员昵称", required = true) private String nickname; /** * 店员等级 */ @NotBlank(message = "等级不能为空") + @ApiModelProperty(value = "店员等级ID", required = true) private String levelId; /** * 性别[0:未知;1:男;2:女] */ @NotNull(message = "性别不能为空") + @ApiModelProperty(value = "性别", required = true, notes = "0:未知;1:男;2:女") private String sex; /** * 头像 */ @NotBlank(message = "头像不能为空") + @ApiModelProperty(value = "头像", required = true, notes = "头像图片URL") private String avatar; /** * 音频 */ @NotBlank(message = "音频不能为空") + @ApiModelProperty(value = "音频", required = true, notes = "音频文件URL") private String audioFrequency; /** * 星座 */ @NotBlank(message = "星座不能为空") + @ApiModelProperty(value = "星座", required = true, example = "天蝎座") private String constellation; /** * 标签 */ + @ApiModelProperty(value = "标签", notes = "店员个人标签，多个标签用逗号分隔") private String label; /** * 个性签名 */ @NotBlank(message = "签名不能为空") + @ApiModelProperty(value = "个性签名", required = true) private String signature; /** * 年龄 */ @NotNull(message = "年龄不能为空") + @ApiModelProperty(value = "年龄", required = true, example = "25") private Long age; /** * 所在国家 */ @NotBlank(message = "国家不能为空") + @ApiModelProperty(value = "所在国家", required = true, example = "中国") private String country; /** * 所在省份 */ @NotBlank(message = "省份不能为空") + @ApiModelProperty(value = "所在省份", required = true, example = "广东省") private String province; /** * 所在城市 */ @NotBlank(message = "城市不能为空") + @ApiModelProperty(value = "所在城市", required = true, example = "深圳市") private String city; /** * 备注 */ + @ApiModelProperty(value = "备注", notes = "店员的备注信息") private String remark; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewQueryVo.java index 76817c1..3ade193 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,44 +16,52 @@ import java.util.List; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "店员资料审核查询参数", description = "查询店员资料审核信息的条件参数") public class PlayClerkUserReviewQueryVo extends BasePageEntity { /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "特定店员的ID") private String clerkId; /** * 店员昵称 */ + @ApiModelProperty(value = "店员昵称", example = "小明", notes = "店员的昵称，支持模糊查询") private String nickname; /** * 性别[0:未知;1:男;2:女] */ + @ApiModelProperty(value = "性别", example = "1", notes = "0:未知;1:男;2:女") private String sex; /** * 手机号码 */ + @ApiModelProperty(value = "手机号码", example = "13800138000", notes = "店员的手机号码") private String phone; /** * 微信号 */ + @ApiModelProperty(value = "微信号", example = "wx123456", notes = "店员的微信号") private String weiChatCode; /** * 审核状态（0：未审核:1：审核通过，2：审核不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0：未审核:1：审核通过，2：审核不通过") private String reviewState; /** * 申请时间 */ + @ApiModelProperty(value = "申请时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "申请时间范围，包含开始和结束时间") private List addTime; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewReturnVo.java index d4ecd00..cb3cee9 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewReturnVo.java @@ -3,6 +3,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.baomidou.mybatisplus.annotation.TableField; import com.fasterxml.jackson.annotation.JsonFormat; import com.starry.admin.common.conf.StringTypeHandler; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import org.springframework.format.annotation.DateTimeFormat; @@ -17,74 +19,89 @@ import java.util.List; * @since 2024/5/19 下午4:21 **/ @Data +@ApiModel(value = "店员资料审核返回数据", description = "店员资料审核信息的返回数据") public class PlayClerkUserReviewReturnVo { + @ApiModelProperty(value = "审核记录ID", example = "1") private String id; /** * 店员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 = "微信号", example = "wx123456") private String weiChatCode; /** * 手机号码 */ + @ApiModelProperty(value = "手机号码", example = "13800138000") private String phone; /** * 昵称 */ + @ApiModelProperty(value = "昵称", example = "小明") private String nickname; /** * 性别[0:未知;1:男;2:女] */ + @ApiModelProperty(value = "性别", example = "1", notes = "0:未知;1:男;2:女") private String sex; /** * 年龄 */ + @ApiModelProperty(value = "年龄", example = "25") private Integer age; /** * 所在省份 */ + @ApiModelProperty(value = "所在省份", example = "广东省") private String province; /** * 所在城市 */ + @ApiModelProperty(value = "所在城市", example = "深圳市") private String city; /** * 备注（相关经验） */ + @ApiModelProperty(value = "备注", example = "有3年相关经验") private String remark; /** * 音频 */ + @ApiModelProperty(value = "音频", example = "https://example.com/audio.mp3") private String audio; /** * 照片 */ @TableField(typeHandler = StringTypeHandler.class) + @ApiModelProperty(value = "照片", example = "[\"https://example.com/photo1.jpg\",\"https://example.com/photo2.jpg\"]") private List album = new ArrayList<>(); /** @@ -92,32 +109,37 @@ public class PlayClerkUserReviewReturnVo { */ @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; /** * 审核状态（0：未审核:1：审核通过，2：审核不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0：未审核:1：审核通过，2：审核不通过") private String reviewState; /** * 审核时间 */ - + @ApiModelProperty(value = "审核时间", example = "2024-01-02 12:00:00") private LocalDateTime reviewTime; /** * 审核人 */ + @ApiModelProperty(value = "审核人", example = "admin") private String reviewBy; /** * 审核内容 */ + @ApiModelProperty(value = "审核内容", example = "资料完整，通过审核") private String reviewCon; /** * 个性签名 */ + @ApiModelProperty(value = "个性签名", example = "用心服务每一位客户") private String signature; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewStateEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewStateEditVo.java index 4b46f6a..b7727f3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewStateEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserReviewStateEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -11,10 +13,12 @@ import java.time.LocalDateTime; * 动态审核 */ @Data +@ApiModel(value = "店员资料审核状态修改参数", description = "修改店员资料审核状态的请求参数") public class PlayClerkUserReviewStateEditVo { @NotBlank(message = "ID不能为空") + @ApiModelProperty(value = "审核记录ID", required = true, example = "1", notes = "店员资料审核记录的ID") private String id; /** @@ -22,15 +26,18 @@ public class PlayClerkUserReviewStateEditVo { */ @NotBlank(message = "审核状态不能为空") @Pattern(regexp = "[12]", message = "审核状态必须为1或2") + @ApiModelProperty(value = "审核状态", required = true, example = "1", notes = "1：审核通过，2：审核不通过") private String reviewState; /** * 发布时间 */ + @ApiModelProperty(value = "审核内容", example = "资料完整，通过审核", notes = "审核的备注内容或拒绝原因") private String reviewCon; /** * 审核时间 */ + @ApiModelProperty(value = "审核时间", hidden = true, notes = "系统自动生成，无需传入") private LocalDateTime reviewTime = LocalDateTime.now(); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserStateEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserStateEditVo.java index 4a09f36..8d30bc3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserStateEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkUserStateEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.clerk.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -9,74 +11,89 @@ import javax.validation.constraints.NotBlank; * @author admin */ @Data +@ApiModel(value = "店员状态编辑对象", description = "修改店员状态信息的参数对象") public class PlayClerkUserStateEditVo { /** * id */ @NotBlank(message = "id不能为空") + @ApiModelProperty(value = "店员ID", required = true, notes = "唯一标识") private String id; /** * 是否推荐状态（1：已推荐，0：未推荐） */ + @ApiModelProperty(value = "是否推荐", notes = "1：已推荐，0：未推荐") private String recommendationState; /** * 是否置顶状态（1：已置顶，0：未置顶） */ + @ApiModelProperty(value = "是否置顶", notes = "1：已置顶，0：未置顶") private String pinToTopState; /** * 在线状态【1：在线，0：离线】 */ + @ApiModelProperty(value = "在线状态", notes = "1：在线，0：离线") private String onlineState; /** * 上架状态【1：上架，0：下架】 */ + @ApiModelProperty(value = "上架状态", notes = "1：上架，0：下架") private String listingState; /** * 显示状态【1：显示，0：隐藏】 */ + @ApiModelProperty(value = "显示状态", notes = "1：显示，0：隐藏") private String displayState; /** * 实名状态【1：已实名，0：未实名】 */ + @ApiModelProperty(value = "实名状态", notes = "1：已实名，0：未实名") private String realState; /** * 是否必须实名【0:非必须实名;1:必须实名;2:跟随店铺设置】 */ + @ApiModelProperty(value = "是否必须实名", notes = "0:非必须实名;1:必须实名;2:跟随店铺设置") private String mandatoryRealState; /** * 随机接单状态【1：允许，0：禁止】 */ + @ApiModelProperty(value = "随机接单状态", notes = "1：允许，0：禁止") private String randomOrderState; /** * 是否固定等级(0:固定等级，1:不固定) */ + @ApiModelProperty(value = "是否固定等级", notes = "0:固定等级，1:不固定") private String fixingLevel; /** * 在职状态（1：在职，0：离职） */ + @ApiModelProperty(value = "在职状态", notes = "1：在职，0：离职", example = "1") private String onboardingState = "1"; /** * 在职状态（1：在职，0：离职） */ + @ApiModelProperty(value = "店员等级ID") private String levelId; + @ApiModelProperty(value = "备注", notes = "店员状态的备注信息") private String remark; + @ApiModelProperty(value = "性别", notes = "0:未知;1:男;2:女") private String sex; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkWagesInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkWagesInfoQueryVo.java index 0a5607c..f9eae21 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkWagesInfoQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/clerk/module/vo/PlayClerkWagesInfoQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.clerk.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -10,24 +12,29 @@ import lombok.EqualsAndHashCode; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "工资历史查询参数", description = "查询店员历史工资结算信息的条件参数") public class PlayClerkWagesInfoQueryVo extends BasePageEntity { /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "特定店员的ID") private String clerkId; /** * 店员分组 */ + @ApiModelProperty(value = "店员分组ID", example = "1", notes = "店员所属分组的ID") private String groupId; /** * 店员上架状态 */ + @ApiModelProperty(value = "店员上架状态", example = "1", notes = "1：上架，0：下架") private String listingState; /** * 统计时间 */ + @ApiModelProperty(value = "统计时间", example = "2024-06", notes = "工资结算的月份，格式为yyyy-MM") private String settlementDate; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomFollowInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomFollowInfoController.java index 74177d4..6e8885e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomFollowInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomFollowInfoController.java @@ -6,6 +6,13 @@ import com.starry.admin.modules.custom.service.IPlayCustomFollowInfoService; 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.ApiImplicitParams; +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.web.bind.annotation.*; @@ -17,6 +24,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-04-30 */ +@Api(tags = "顾客关注管理", description = "顾客关注店员信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/play/follow") public class PlayCustomFollowInfoController { @@ -26,9 +34,13 @@ public class PlayCustomFollowInfoController { /** * 查询顾客关注陪聊信息列表 */ + @ApiOperation(value = "分页查询关注列表", notes = "分页查询顾客关注店员信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomFollowInfoEntity.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('play:info:list')") @GetMapping("/list") - public R list(PlayCustomFollowInfoEntity playCustomFollowInfo) { + public R list(@ApiParam(value = "查询条件") PlayCustomFollowInfoEntity playCustomFollowInfo) { IPage list = playCustomFollowInfoService.selectPlayCustomFollowInfoByPage(playCustomFollowInfo); return R.ok(list); } @@ -36,6 +48,11 @@ public class PlayCustomFollowInfoController { /** * 获取顾客关注陪聊信息详细信息 */ + @ApiOperation(value = "获取关注详情", notes = "根据ID获取顾客关注店员详细信息") + @ApiImplicitParam(name = "id", value = "关注记录ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomFollowInfoEntity.class) + }) @PreAuthorize("@customSs.hasPermission('play:info:query')") @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { @@ -45,10 +62,15 @@ public class PlayCustomFollowInfoController { /** * 新增顾客关注陪聊信息 */ + @ApiOperation(value = "新增关注记录", notes = "创建新的顾客关注店员信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @PreAuthorize("@customSs.hasPermission('play:info:create')") @Log(title = "顾客关注陪聊信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCustomFollowInfoEntity playCustomFollowInfo) { + public R create(@ApiParam(value = "关注信息", required = true) @RequestBody PlayCustomFollowInfoEntity playCustomFollowInfo) { boolean success = playCustomFollowInfoService.create(playCustomFollowInfo); if (success) { return R.ok(); @@ -59,10 +81,16 @@ public class PlayCustomFollowInfoController { /** * 修改顾客关注陪聊信息 */ + @ApiOperation(value = "修改关注记录", notes = "根据ID修改顾客关注店员信息") + @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('play:info:edit')") @Log(title = "顾客关注陪聊信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCustomFollowInfoEntity playCustomFollowInfo) { + public R update(@PathVariable String id, @ApiParam(value = "关注信息", required = true) @RequestBody PlayCustomFollowInfoEntity playCustomFollowInfo) { playCustomFollowInfo.setId(id); boolean success = playCustomFollowInfoService.update(playCustomFollowInfo); if (success) { @@ -74,6 +102,11 @@ public class PlayCustomFollowInfoController { /** * 删除顾客关注陪聊信息 */ + @ApiOperation(value = "删除关注记录", notes = "根据ID批量删除顾客关注店员信息") + @ApiImplicitParam(name = "ids", value = "关注记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @PreAuthorize("@customSs.hasPermission('play:info:remove')") @Log(title = "顾客关注陪聊信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomGiftInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomGiftInfoController.java index 3253b9d..fd07cd2 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomGiftInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomGiftInfoController.java @@ -6,6 +6,13 @@ import com.starry.admin.modules.custom.service.IPlayCustomGiftInfoService; 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.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; @@ -16,6 +23,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-06-05 */ +@Api(tags = "顾客礼物管理", description = "顾客与礼物关系管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/custom/giff") public class PlayCustomGiftInfoController { @@ -25,8 +33,12 @@ public class PlayCustomGiftInfoController { /** * 查询顾客和礼物关系列表 */ + @ApiOperation(value = "分页查询礼物列表", notes = "分页查询顾客与礼物关系列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomGiftInfoEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayCustomGiftInfoEntity playCustomGiftInfo) { + public R list(@ApiParam(value = "查询条件") PlayCustomGiftInfoEntity playCustomGiftInfo) { IPage list = playCustomGiftInfoService.selectPlayCustomGiftInfoByPage(playCustomGiftInfo); return R.ok(list); } @@ -34,6 +46,11 @@ public class PlayCustomGiftInfoController { /** * 获取顾客和礼物关系详细信息 */ + @ApiOperation(value = "获取礼物详情", notes = "根据ID获取顾客与礼物关系详细信息") + @ApiImplicitParam(name = "id", value = "礼物关系ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomGiftInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playCustomGiftInfoService.selectPlayCustomGiftInfoById(id)); @@ -42,9 +59,14 @@ public class PlayCustomGiftInfoController { /** * 新增顾客和礼物关系 */ + @ApiOperation(value = "新增礼物关系", notes = "创建新的顾客与礼物关系信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "顾客和礼物关系", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCustomGiftInfoEntity playCustomGiftInfo) { + public R create(@ApiParam(value = "礼物关系信息", required = true) @RequestBody PlayCustomGiftInfoEntity playCustomGiftInfo) { boolean success = playCustomGiftInfoService.create(playCustomGiftInfo); if (success) { return R.ok(); @@ -55,9 +77,15 @@ public class PlayCustomGiftInfoController { /** * 修改顾客和礼物关系 */ + @ApiOperation(value = "修改礼物关系", notes = "根据ID修改顾客与礼物关系信息") + @ApiImplicitParam(name = "id", value = "礼物关系ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "顾客和礼物关系", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCustomGiftInfoEntity playCustomGiftInfo) { + public R update(@PathVariable String id, @ApiParam(value = "礼物关系信息", required = true) @RequestBody PlayCustomGiftInfoEntity playCustomGiftInfo) { playCustomGiftInfo.setId(id); boolean success = playCustomGiftInfoService.update(playCustomGiftInfo); if (success) { @@ -69,6 +97,11 @@ public class PlayCustomGiftInfoController { /** * 删除顾客和礼物关系 */ + @ApiOperation(value = "删除礼物关系", notes = "根据ID批量删除顾客与礼物关系信息") + @ApiImplicitParam(name = "ids", value = "礼物关系ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "顾客和礼物关系", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLeaveMsgController.java b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLeaveMsgController.java index f70213e..19f8625 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLeaveMsgController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLeaveMsgController.java @@ -8,6 +8,13 @@ import com.starry.admin.modules.custom.service.IPlayCustomLeaveMsgService; 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.ApiImplicitParams; +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.*; @@ -19,6 +26,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-07 */ +@Api(tags = "顾客留言管理", description = "顾客留言信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/custom/leave") public class PlayCustomLeaveMsgController { @@ -28,8 +36,12 @@ public class PlayCustomLeaveMsgController { /** * 分页查询顾客留言列表 */ + @ApiOperation(value = "分页查询留言列表", notes = "分页查询顾客留言信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomLeaveMsgReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayCustomLeaveMsgQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayCustomLeaveMsgQueryVo vo) { IPage list = playCustomLeaveMsgService.selectByPage(vo); return R.ok(list); } @@ -37,6 +49,11 @@ public class PlayCustomLeaveMsgController { /** * 获取顾客留言详细信息 */ + @ApiOperation(value = "获取留言详情", notes = "根据ID获取顾客留言详细信息") + @ApiImplicitParam(name = "id", value = "留言ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomLeaveMsgEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playCustomLeaveMsgService.selectPlayCustomLeaveMsgById(id)); @@ -45,10 +62,15 @@ public class PlayCustomLeaveMsgController { /** * 新增顾客留言 */ + @ApiOperation(value = "新增留言", notes = "创建新的顾客留言信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) //@PreAuthorize("@customSs.hasPermission('custom:leave:add')") @Log(title = "顾客留言", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCustomLeaveMsgEntity playCustomLeaveMsg) { + public R create(@ApiParam(value = "留言信息", required = true) @RequestBody PlayCustomLeaveMsgEntity playCustomLeaveMsg) { boolean success = playCustomLeaveMsgService.create(playCustomLeaveMsg); if (success) { return R.ok(); @@ -59,10 +81,16 @@ public class PlayCustomLeaveMsgController { /** * 修改顾客留言 */ + @ApiOperation(value = "修改留言", notes = "根据ID修改顾客留言信息") + @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('custom:leave:update')") @Log(title = "顾客留言", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCustomLeaveMsgEntity playCustomLeaveMsg) { + public R update(@PathVariable String id, @ApiParam(value = "留言信息", required = true) @RequestBody PlayCustomLeaveMsgEntity playCustomLeaveMsg) { playCustomLeaveMsg.setId(id); boolean success = playCustomLeaveMsgService.update(playCustomLeaveMsg); if (success) { @@ -74,6 +102,11 @@ public class PlayCustomLeaveMsgController { /** * 删除顾客留言 */ + @ApiOperation(value = "删除留言", notes = "根据ID批量删除顾客留言信息") + @ApiImplicitParam(name = "ids", value = "留言ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) //@PreAuthorize("@customSs.hasPermission('custom:leave:delete')") @Log(title = "顾客留言", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLevelInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLevelInfoController.java index a9d342e..47770f5 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLevelInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomLevelInfoController.java @@ -10,6 +10,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.web.bind.annotation.*; import javax.annotation.Resource; @@ -23,6 +29,7 @@ import java.util.List; */ @RestController @RequestMapping("/custom/level") +@Api(tags = "顾客等级管理", description = "顾客等级信息管理相关接口，包括查询、新增、修改和删除等操作") public class PlayCustomLevelInfoController { @Resource private IPlayCustomLevelInfoService playCustomLevelInfoService; @@ -31,6 +38,10 @@ public class PlayCustomLevelInfoController { * 查询顾客等级列表 */ @PostMapping("/listAll") + @ApiOperation(value = "查询等级列表", notes = "获取所有顾客等级信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomLevelReturnVo.class, responseContainer = "List") + }) public R listAll() { List list = playCustomLevelInfoService.selectPlayCustomLevelInfoByPage(); return R.ok(ConvertUtil.entityToVoList(list, PlayCustomLevelReturnVo.class)); @@ -40,6 +51,11 @@ public class PlayCustomLevelInfoController { * 获取顾客等级详细信息 */ @GetMapping(value = "/{id}") + @ApiOperation(value = "获取等级详情", notes = "根据ID获取顾客等级详细信息") + @ApiImplicitParam(name = "id", value = "等级ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomLevelInfoEntity.class) + }) public R getInfo(@PathVariable("id") String id) { return R.ok(playCustomLevelInfoService.selectPlayCustomLevelInfoById(id)); } @@ -51,7 +67,12 @@ public class PlayCustomLevelInfoController { //@PreAuthorize("@customSs.hasPermission('custom:level:add')") @Log(title = "店员等级", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCustomLevelAddVo vo) { + @ApiOperation(value = "新增等级", notes = "创建新的顾客等级信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) + public R create(@ApiParam(value = "等级信息", required = true) @RequestBody PlayCustomLevelAddVo vo) { PlayCustomLevelInfoEntity entity = ConvertUtil.entityToVo(vo, PlayCustomLevelInfoEntity.class); int level = playCustomLevelInfoService.selectMaxLevel(); entity.setLevel(level + 1); @@ -69,7 +90,13 @@ public class PlayCustomLevelInfoController { //@PreAuthorize("@customSs.hasPermission('custom:level:update')") @Log(title = "顾客等级", businessType = BusinessType.UPDATE) @PostMapping(value = "/update") - public R update(@RequestBody PlayCustomLevelEditVo vo) { + @ApiOperation(value = "修改等级", notes = "修改顾客等级信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败"), + @ApiResponse(code = 400, message = "对象不存在") + }) + public R update(@ApiParam(value = "等级信息", required = true) @RequestBody PlayCustomLevelEditVo vo) { if (playCustomLevelInfoService.selectPlayCustomLevelInfoById(vo.getId()) == null) { throw new CustomException("对象不存在"); } @@ -86,6 +113,11 @@ public class PlayCustomLevelInfoController { */ @Log(title = "店员等级", businessType = BusinessType.DELETE) @DeleteMapping("delMaxLevel") + @ApiOperation(value = "删除最高等级", notes = "删除系统中的最高等级") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 400, message = "最后一级,不允许删除") + }) public R remove() { int level = playCustomLevelInfoService.selectMaxLevel(); if (level <= 1) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomRankingController.java b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomRankingController.java index f1bdd2f..98d8f2e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomRankingController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomRankingController.java @@ -5,6 +5,11 @@ import com.starry.admin.modules.custom.module.vo.PlayCustomRankingQueryVo; import com.starry.admin.modules.custom.module.vo.PlayCustomRankingReturnVo; import com.starry.admin.modules.custom.service.IPlayCustomUserInfoService; 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.PostMapping; import org.springframework.web.bind.annotation.RequestBody; @@ -19,6 +24,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-04-08 */ +@Api(tags = "顾客排名管理", description = "顾客消费排名相关接口，包括查询排名列表等操作") @RestController @RequestMapping("/custom/ranking") public class PlayCustomRankingController { @@ -28,8 +34,12 @@ public class PlayCustomRankingController { /** * 查询顾客排名列表 */ + @ApiOperation(value = "分页查询排名列表", notes = "分页查询顾客消费排名信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomRankingReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayCustomRankingQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayCustomRankingQueryVo vo) { IPage list = playCustomUserInfoService.selectRankingByPage(vo); return R.ok(list); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomUserInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomUserInfoController.java index d84d1e5..9e6d5d0 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomUserInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/controller/PlayCustomUserInfoController.java @@ -10,6 +10,13 @@ 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.ApiImplicitParams; +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.*; @@ -21,6 +28,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-04-08 */ +@Api(tags = "顾客管理", description = "顾客信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/custom/user") public class PlayCustomUserInfoController { @@ -30,8 +38,12 @@ public class PlayCustomUserInfoController { /** * 查询顾客列表 */ + @ApiOperation(value = "分页查询顾客列表", notes = "分页查询顾客信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomUserReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayCustomUserQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayCustomUserQueryVo vo) { IPage list = playCustomUserInfoService.selectByPage(vo); return R.ok(list); } @@ -39,6 +51,11 @@ public class PlayCustomUserInfoController { /** * 获取顾客详细信息 */ + @ApiOperation(value = "获取顾客详情", notes = "根据ID获取顾客详细信息") + @ApiImplicitParam(name = "id", value = "顾客ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomUserInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playCustomUserInfoService.selectById(id)); @@ -47,9 +64,14 @@ public class PlayCustomUserInfoController { /** * 新增顾客 */ + @ApiOperation(value = "新增顾客", notes = "创建新的顾客信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "顾客", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCustomUserInfoEntity playCustomUserInfo) { + public R create(@ApiParam(value = "顾客信息", required = true) @RequestBody PlayCustomUserInfoEntity playCustomUserInfo) { boolean success = playCustomUserInfoService.create(playCustomUserInfo); if (success) { return R.ok(); @@ -60,9 +82,14 @@ public class PlayCustomUserInfoController { /** * 修改顾客状态 */ + @ApiOperation(value = "修改顾客状态", notes = "修改顾客的状态信息，如黑名单状态、关注状态等") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "顾客", businessType = BusinessType.UPDATE) @PostMapping(value = "/updateState") - public R updateState(@Validated @RequestBody PlayCustomUserStateEditVo vo) { + public R updateState(@ApiParam(value = "顾客状态信息", required = true) @Validated @RequestBody PlayCustomUserStateEditVo vo) { PlayCustomUserInfoEntity entity = ConvertUtil.entityToVo(vo, PlayCustomUserInfoEntity.class); boolean success = playCustomUserInfoService.update(entity); if (success) { @@ -74,9 +101,15 @@ public class PlayCustomUserInfoController { /** * 修改顾客 */ + @ApiOperation(value = "修改顾客信息", notes = "根据ID修改顾客基本信息") + @ApiImplicitParam(name = "id", value = "顾客ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "顾客", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCustomUserInfoEntity playCustomUserInfo) { + public R update(@PathVariable String id, @ApiParam(value = "顾客信息", required = true) @RequestBody PlayCustomUserInfoEntity playCustomUserInfo) { playCustomUserInfo.setId(id); boolean success = playCustomUserInfoService.update(playCustomUserInfo); if (success) { @@ -88,6 +121,11 @@ public class PlayCustomUserInfoController { /** * 删除顾客 */ + @ApiOperation(value = "删除顾客", notes = "根据ID批量删除顾客信息") + @ApiImplicitParam(name = "ids", value = "顾客ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "顾客", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgQueryVo.java index ee22582..471ddb0 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgQueryVo.java @@ -1,6 +1,10 @@ package com.starry.admin.modules.custom.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; +import lombok.Data; +import lombok.EqualsAndHashCode; /** * 顾客留言查询对象 @@ -8,5 +12,14 @@ import com.starry.common.domain.BasePageEntity; * @author admin * @since 2024/5/7 16:29 **/ +@Data +@EqualsAndHashCode(callSuper = true) +@ApiModel(value = "顾客留言查询参数", description = "查询顾客留言信息的条件参数") public class PlayCustomLeaveMsgQueryVo extends BasePageEntity { + + @ApiModelProperty(value = "顾客ID", example = "1", notes = "特定顾客的ID") + private String customId; + + @ApiModelProperty(value = "留言内容", example = "服务很好", notes = "留言的内容，支持模糊查询") + private String content; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgReturnVo.java index 0b2f40f..c55fd89 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLeaveMsgReturnVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.custom.module.vo; import com.baomidou.mybatisplus.annotation.TableField; import com.starry.admin.common.conf.StringTypeHandler; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.util.Date; @@ -14,47 +16,56 @@ import java.util.List; * @since 2024/5/7 16:29 **/ @Data +@ApiModel(value = "顾客留言返回数据", description = "顾客留言信息的返回数据") public class PlayCustomLeaveMsgReturnVo { /** * UUID */ + @ApiModelProperty(value = "留言ID", example = "1") private String id; /** * 留言内容 */ + @ApiModelProperty(value = "留言内容", example = "服务很好，希望以后再次合作") private String content; /** * 图片 */ + @ApiModelProperty(value = "留言图片", example = "[\"https://example.com/image1.jpg\",\"https://example.com/image2.jpg\"]") @TableField(typeHandler = StringTypeHandler.class) private List images; /** * 留言时间 */ + @ApiModelProperty(value = "留言时间", example = "2024-01-01 12:00:00") private Date msgTime; /** * 备注 */ + @ApiModelProperty(value = "备注", example = "重要留言") private String remark; /** * 顾客Id */ + @ApiModelProperty(value = "顾客ID", example = "1") private String customId; /** * 顾客昵称 */ + @ApiModelProperty(value = "顾客头像", example = "https://example.com/avatar.jpg") private String customAvatar; /** * 头像 */ + @ApiModelProperty(value = "顾客昵称", example = "张三") private String customNickname; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelAddVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelAddVo.java index 8bf87d4..57d6db4 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelAddVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelAddVo.java @@ -1,16 +1,20 @@ package com.starry.admin.modules.custom.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @Data +@ApiModel(value = "顾客等级添加参数", description = "新增顾客等级信息的请求参数") public class PlayCustomLevelAddVo { /** * 等级名称 */ @NotBlank(message = "等级名称不能为空") + @ApiModelProperty(value = "等级名称", required = true, example = "钻石会员", notes = "顾客等级的名称") private String name; @@ -18,17 +22,20 @@ public class PlayCustomLevelAddVo { * 上一级消费金额 */ @NotBlank(message = "消费金额不能为空") + @ApiModelProperty(value = "消费金额", required = true, example = "1000", notes = "达到该等级需要的消费金额") private String consumptionAmount; /** * 满减比例 */ @NotBlank(message = "满减比例不能为空") + @ApiModelProperty(value = "满减比例", required = true, example = "95", notes = "该等级享受的满减折扣比例，如95表示95折") private Integer discount; /** * 头像框地址 */ + @ApiModelProperty(value = "头像框地址", example = "https://example.com/frame.png", notes = "该等级专属的头像框图片地址") private String avatarFrameAddress; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelEditVo.java index 634e7f6..3abe508 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelEditVo.java @@ -1,22 +1,27 @@ package com.starry.admin.modules.custom.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @Data +@ApiModel(value = "顾客等级修改参数", description = "修改顾客等级信息的请求参数") public class PlayCustomLevelEditVo { /** * UUID */ @NotBlank(message = "ID不能为空") + @ApiModelProperty(value = "等级ID", required = true, example = "1", notes = "顾客等级的ID") private String id; /** * 等级名称 */ @NotBlank(message = "等级名称不能为空") + @ApiModelProperty(value = "等级名称", required = true, example = "钻石会员", notes = "顾客等级的名称") private String name; @@ -24,17 +29,20 @@ public class PlayCustomLevelEditVo { * 上一级消费金额 */ @NotBlank(message = "消费金额不能为空") + @ApiModelProperty(value = "消费金额", required = true, example = "1000", notes = "达到该等级需要的消费金额") private String consumptionAmount; /** * 满减比例 */ @NotBlank(message = "满减比例不能为空") + @ApiModelProperty(value = "满减比例", required = true, example = "95", notes = "该等级享受的满减折扣比例，如95表示95折") private Integer discount; /** * 头像框地址 */ + @ApiModelProperty(value = "头像框地址", example = "https://example.com/frame.png", notes = "该等级专属的头像框图片地址") private String avatarFrameAddress; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelReturnVo.java index c4f7209..b10dae5 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomLevelReturnVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.custom.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; /** @@ -8,36 +10,43 @@ import lombok.Data; * @author admin */ @Data +@ApiModel(value = "顾客等级返回数据", description = "顾客等级信息的返回数据") public class PlayCustomLevelReturnVo { /** * UUID */ + @ApiModelProperty(value = "等级ID", example = "1") private String id; /** * 等级名称 */ + @ApiModelProperty(value = "等级名称", example = "钻石会员") private String name; /** * 等级数字（排序字段） */ + @ApiModelProperty(value = "等级数值", example = "3", notes = "等级数字，用于排序") private Integer level; /** * 上一级消费金额 */ + @ApiModelProperty(value = "消费金额", example = "1000", notes = "达到该等级需要的消费金额") private String consumptionAmount; /** * 满减比例 */ + @ApiModelProperty(value = "满减比例", example = "95", notes = "该等级享受的满减折扣比例，如95表示95折") private Integer discount; /** * 头像框地址 */ + @ApiModelProperty(value = "头像框地址", example = "https://example.com/frame.png") private String avatarFrameAddress; diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingQueryVo.java index 2c0b3b6..9525dc3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.custom.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,14 +16,17 @@ import java.util.List; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "顾客排名查询参数", description = "查询顾客消费排名信息的条件参数") public class PlayCustomRankingQueryVo extends BasePageEntity { /** * userId */ + @ApiModelProperty(value = "顾客ID", example = "1", notes = "特定顾客的ID") private String id; /** * 下单时间 */ + @ApiModelProperty(value = "下单时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "下单时间范围，包含开始和结束时间") private List purchaserTime; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingReturnVo.java index 6987c85..dea5e21 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomRankingReturnVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.custom.module.vo; import com.fasterxml.jackson.annotation.JsonIgnore; import com.starry.admin.modules.order.module.entity.PlayOrderInfoEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.math.BigDecimal; @@ -15,67 +17,80 @@ import java.util.List; * @since 2024/5/14 下午7:47 **/ @Data +@ApiModel(value = "顾客排名返回数据", description = "顾客消费排名信息的返回数据") public class PlayCustomRankingReturnVo { /** * UUID */ + @ApiModelProperty(value = "顾客ID", example = "1") private String id; /** * 顾客昵称 */ + @ApiModelProperty(value = "顾客昵称", example = "张三") private String nickname; /** * 头像 */ + @ApiModelProperty(value = "头像", example = "https://example.com/avatar.jpg") private String avatar; /** * 排名 */ + @ApiModelProperty(value = "排名", example = "1", notes = "顾客消费排名索引") private Integer rankingIndex; /** * 订单列表 */ @JsonIgnore + @ApiModelProperty(value = "订单列表", hidden = true) private List orderInfos; /** * 下单时间-起始时间 */ + @ApiModelProperty(value = "下单起始时间", example = "2024-01-01 00:00:00") private String beginPurchaserTime; /** * 下单时间-终止时间 */ + @ApiModelProperty(value = "下单终止时间", example = "2024-12-31 23:59:59") private String endPurchaserTime; /** * 订单总数 */ + @ApiModelProperty(value = "订单总数", example = "10") private String orderNumber; /** * 续单总数 */ + @ApiModelProperty(value = "续单总数", example = "5", notes = "顾客续费订单的总数量") private String orderContinueNumber; /** * 订单单价 */ + @ApiModelProperty(value = "订单单价", example = "100.00") private String orderPrice; /** * 订单总金额 */ + @ApiModelProperty(value = "订单总金额", example = "1000.00") private BigDecimal orderTotalAmount; /** * 统计时间 */ + @ApiModelProperty(value = "统计时间", example = "2024-01-01") private String statisticalTime = LocalDate.now().toString(); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserQueryVo.java index f1c04e4..d0f8242 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.custom.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,99 +16,118 @@ import java.util.List; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "顾客查询参数", description = "查询顾客信息的条件参数") public class PlayCustomUserQueryVo extends BasePageEntity { + @ApiModelProperty(value = "顾客ID", example = "1", notes = "特定顾客的ID") private String id; /** * 用户的标识，对当前公众号唯一 */ + @ApiModelProperty(value = "OpenID", example = "o6_bmjrPTlm6_2sgVt7hMZOPfL2M", notes = "微信用户的唯一标识") private String openid; /** * 顾客昵称 */ + @ApiModelProperty(value = "昵称", example = "张三", notes = "顾客的昵称，支持模糊查询") private String nickname; /** * 顾客性别（0:未知;1:男,2:女） */ + @ApiModelProperty(value = "性别", example = "1", notes = "0:未知;1:男;2:女") private String sex; /** * 微信号 */ + @ApiModelProperty(value = "微信号", example = "zhangsan123", notes = "顾客的微信号") private String weiChatCode; /** * 绑定手机状态[0:未绑定,1:绑定] */ + @ApiModelProperty(value = "绑定手机状态", example = "1", notes = "0:未绑定,1:绑定") private String mobilePhoneState; /** * 手机号码 */ + @ApiModelProperty(value = "手机号码", example = "13800138000", notes = "顾客的手机号码") private String phone; /** * 等级ID */ + @ApiModelProperty(value = "等级ID", example = "1", notes = "顾客等级的ID") private String levelId; /** * 余额状态[0:不存在余额，1:存在余额] */ + @ApiModelProperty(value = "余额状态", example = "1", notes = "0:不存在余额，1:存在余额") private String accountState; /** * 关注状态[0:未关注，1:已关注] */ + @ApiModelProperty(value = "关注状态", example = "1", notes = "0:未关注，1:已关注") private String subscribeState; /** * 违规状态[0:未违规,1:违规] */ + @ApiModelProperty(value = "违规状态", example = "0", notes = "0:未违规,1:违规") private String violationState; /** * 是否下单状态[0:未下单过，1:下单过] */ + @ApiModelProperty(value = "下单状态", example = "1", notes = "0:未下单过，1:下单过") private String purchaseState; /** * 黑名单状态[0:非黑名单，1:黑名单] */ + @ApiModelProperty(value = "黑名单状态", example = "0", notes = "0:非黑名单，1:黑名单") private String blacklistState; /** * 注册时间 */ + @ApiModelProperty(value = "注册时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "注册时间范围，包含开始和结束时间") private List registrationTime; /** * 首次下单时间 */ + @ApiModelProperty(value = "首次下单时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "首次下单时间范围，包含开始和结束时间") private List firstPurchaseTime; /** * 最后一次下单时间 */ + @ApiModelProperty(value = "最后下单时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "最后一次下单时间范围，包含开始和结束时间") private List lastPurchaseTime; /** * 备注 */ + @ApiModelProperty(value = "备注", example = "重要客户", notes = "顾客相关备注信息") private String remark; /** * 排序字段 */ + @ApiModelProperty(value = "排序字段", example = "registrationTime", notes = "排序的字段名称") private String sort; diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserReturnVo.java index 95d0fb5..f7be0f4 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserReturnVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.custom.module.vo; import com.starry.admin.modules.order.module.entity.PlayOrderInfoEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.math.BigDecimal; @@ -14,161 +16,190 @@ import java.util.List; * @since 2024/5/14 下午7:47 **/ @Data +@ApiModel(value = "顾客返回数据", description = "顾客信息的返回数据") public class PlayCustomUserReturnVo { /** * UUID */ + @ApiModelProperty(value = "顾客ID", example = "1") private String id; /** * 租户ID */ + @ApiModelProperty(value = "租户ID", example = "tenant123", notes = "系统租户标识") private String tenantId; /** * 用户的标识，对当前公众号唯一 */ + @ApiModelProperty(value = "OpenID", example = "o6_bmjrPTlm6_2sgVt7hMZOPfL2M", notes = "微信用户的唯一标识") private String openid; /** * 顾客昵称 */ + @ApiModelProperty(value = "昵称", example = "张三") private String nickname; /** * 顾客性别（0:未知;1:男,2:女） */ + @ApiModelProperty(value = "性别", example = "1", notes = "0:未知;1:男;2:女") private Integer sex; /** * 头像 */ + @ApiModelProperty(value = "头像", example = "https://example.com/avatar.jpg") private String avatar; /** * 手机号码 */ + @ApiModelProperty(value = "手机号码", example = "13800138000") private String phone; /** * 微信号码 */ + @ApiModelProperty(value = "微信号", example = "zhangsan123") private String weiChatCode; /** * 所在国家 */ + @ApiModelProperty(value = "国家", example = "中国") private String country; /** * 所在省份 */ + @ApiModelProperty(value = "省份", example = "广东省") private String province; /** * 所在城市 */ + @ApiModelProperty(value = "城市", example = "深圳市") private String city; /** * 账户余额 */ + @ApiModelProperty(value = "账户余额", example = "1000.50") private BigDecimal accountBalance; /** * 余额状态[0:不存在余额，1:存在余额] */ + @ApiModelProperty(value = "余额状态", example = "1", notes = "0:不存在余额，1:存在余额") private String accountState; /** * 关注状态[0:未关注，1:已关注] */ + @ApiModelProperty(value = "关注状态", example = "1", notes = "0:未关注，1:已关注") private String subscribeState; /** * 黑名单状态[0:非黑名单，1:黑名单] */ + @ApiModelProperty(value = "黑名单状态", example = "0", notes = "0:非黑名单，1:黑名单") private String blacklistState; /** * 违规状态[0:未违规,1:违规] */ + @ApiModelProperty(value = "违规状态", example = "0", notes = "0:未违规,1:违规") private String violationState; /** * 是否下单状态[0:未下单过，1:下单过] */ + @ApiModelProperty(value = "下单状态", example = "1", notes = "0:未下单过，1:下单过") private String purchaseState; /** * 绑定手机状态[0:未绑定,1:绑定] */ + @ApiModelProperty(value = "绑定手机状态", example = "1", notes = "0:未绑定,1:绑定") private String mobilePhoneState; /** * 实名状态【1：已实名，0：未实名】 */ + @ApiModelProperty(value = "实名状态", example = "1", notes = "1：已实名，0：未实名") private String realState; /** * 是否必须实名【2:跟随店铺设置，1：必须实名，0：非必须实名】 */ + @ApiModelProperty(value = "必须实名状态", example = "1", notes = "2:跟随店铺设置，1：必须实名，0：非必须实名") private String mandatoryRealState; /** * 注册时间 */ + @ApiModelProperty(value = "注册时间", example = "2024-01-01 12:00:00") private Date registrationTime; /** * 上次登录时间 */ + @ApiModelProperty(value = "上次登录时间", example = "2024-01-15 12:00:00") private Date lastLoginTime; /** * 首次下单时间 */ + @ApiModelProperty(value = "首次下单时间", example = "2024-01-05 12:00:00") private Date firstPurchaseTime; /** * 最后一次下单时间 */ + @ApiModelProperty(value = "最后下单时间", example = "2024-01-20 12:00:00") private Date lastPurchaseTime; /** * 备注 */ + @ApiModelProperty(value = "备注", example = "重要客户") private String remark; /** * 等级ID */ + @ApiModelProperty(value = "等级ID", example = "1") private String levelId; /** * 等级名称 */ + @ApiModelProperty(value = "等级名称", example = "钻石会员") private String levelName; /** * 订单列表 */ + @ApiModelProperty(value = "订单列表", notes = "顾客的订单列表") private List orderInfos; /** * 订单总数 */ + @ApiModelProperty(value = "订单总数", example = "10") private String orderNumber; /** * 订单单价 */ + @ApiModelProperty(value = "订单单价", example = "100.00") private String orderPrice; /** * 订单总金额 */ + @ApiModelProperty(value = "订单总金额", example = "1000.00") private BigDecimal orderTotalAmount; - - - } diff --git a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserStateEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserStateEditVo.java index 4de591b..2418267 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserStateEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/custom/module/vo/PlayCustomUserStateEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.custom.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -9,55 +11,66 @@ import javax.validation.constraints.NotBlank; * @author admin */ @Data +@ApiModel(value = "顾客状态修改参数", description = "修改顾客状态信息的请求参数") public class PlayCustomUserStateEditVo { /** * id */ @NotBlank(message = "id不能为空") + @ApiModelProperty(value = "顾客ID", required = true, example = "1", notes = "顾客的ID") private String id; /** * 余额状态[0:不存在余额，1:存在余额] */ + @ApiModelProperty(value = "余额状态", example = "1", notes = "0:不存在余额，1:存在余额") private String accountState; /** * 关注状态[0:未关注，1:已关注] */ + @ApiModelProperty(value = "关注状态", example = "1", notes = "0:未关注，1:已关注") private String subscribeState; /** * 黑名单状态[0:非黑名单，1:黑名单] */ + @ApiModelProperty(value = "黑名单状态", example = "0", notes = "0:非黑名单，1:黑名单") private String blacklistState; /** * 违规状态[0:未违规,1:违规] */ + @ApiModelProperty(value = "违规状态", example = "0", notes = "0:未违规,1:违规") private String violationState; /** * 是否下单状态[0:未未下单，1:下单过] */ + @ApiModelProperty(value = "下单状态", example = "1", notes = "0:未下单过，1:下单过") private String purchaseState; /** * 绑定手机状态[0:未绑定,1:绑定] */ + @ApiModelProperty(value = "绑定手机状态", example = "1", notes = "0:未绑定,1:绑定") private String mobilePhoneState; /** * 实名状态【1：已实名，0：未实名】 */ + @ApiModelProperty(value = "实名状态", example = "1", notes = "1：已实名，0：未实名") private String realState; /** * 是否必须实名【0:非必须实名;1:必须实名;2:跟随店铺设置】 */ + @ApiModelProperty(value = "必须实名状态", example = "1", notes = "2:跟随店铺设置，1：必须实名，0：非必须实名") private String mandatoryRealState; + @ApiModelProperty(value = "备注", example = "重要客户", notes = "顾客相关备注信息") private String remark; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderComplaintInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderComplaintInfoController.java index 6dc2839..902c8ca 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderComplaintInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderComplaintInfoController.java @@ -8,6 +8,12 @@ import com.starry.admin.modules.order.service.IPlayOrderComplaintInfoService; 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.*; @@ -19,6 +25,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-07 */ +@Api(tags = "订单投诉管理", description = "订单投诉信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/order/complaint") public class PlayOrderComplaintInfoController { @@ -28,8 +35,12 @@ public class PlayOrderComplaintInfoController { /** * 查询订单投诉信息列表 */ + @ApiOperation(value = "分页查询投诉列表", notes = "分页查询订单投诉信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderComplaintReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayOrderComplaintQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderComplaintQueryVo vo) { IPage list = playOrderComplaintInfoService.selectByPage(vo); return R.ok(list); } @@ -37,6 +48,11 @@ public class PlayOrderComplaintInfoController { /** * 获取订单投诉信息详细信息 */ + @ApiOperation(value = "获取投诉详情", notes = "根据ID获取订单投诉详细信息") + @ApiImplicitParam(name = "id", value = "投诉记录ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderComplaintInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playOrderComplaintInfoService.selectPlayOrderComplaintInfoById(id)); @@ -45,10 +61,15 @@ public class PlayOrderComplaintInfoController { /** * 新增订单投诉信息 */ + @ApiOperation(value = "新增投诉记录", notes = "创建新的订单投诉信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) //@PreAuthorize("@customSs.hasPermission('order:complaint:add')") @Log(title = "订单投诉信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayOrderComplaintInfoEntity playOrderComplaintInfo) { + public R create(@ApiParam(value = "投诉信息", required = true) @RequestBody PlayOrderComplaintInfoEntity playOrderComplaintInfo) { boolean success = playOrderComplaintInfoService.create(playOrderComplaintInfo); if (success) { return R.ok(); @@ -59,10 +80,16 @@ public class PlayOrderComplaintInfoController { /** * 修改订单投诉信息 */ + @ApiOperation(value = "修改投诉记录", notes = "根据ID修改订单投诉信息") + @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('order:complaint:update')") @Log(title = "订单投诉信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayOrderComplaintInfoEntity playOrderComplaintInfo) { + public R update(@PathVariable String id, @ApiParam(value = "投诉信息", required = true) @RequestBody PlayOrderComplaintInfoEntity playOrderComplaintInfo) { playOrderComplaintInfo.setId(id); boolean success = playOrderComplaintInfoService.update(playOrderComplaintInfo); if (success) { @@ -74,6 +101,11 @@ public class PlayOrderComplaintInfoController { /** * 删除订单投诉信息 */ + @ApiOperation(value = "删除投诉记录", notes = "根据ID批量删除订单投诉信息") + @ApiImplicitParam(name = "ids", value = "投诉记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) //@PreAuthorize("@customSs.hasPermission('order:complaint:delete')") @Log(title = "订单投诉信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderContinueInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderContinueInfoController.java index 36cb1f1..4ff21ed 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderContinueInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderContinueInfoController.java @@ -6,6 +6,11 @@ import com.starry.admin.modules.order.module.vo.PlayOrderContinueReturnVo; import com.starry.admin.modules.order.module.vo.PlayOrderReviewStateEditVo; import com.starry.admin.modules.order.service.IPlayOrderContinueInfoService; 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.PostMapping; import org.springframework.web.bind.annotation.RequestBody; @@ -20,6 +25,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-10 */ +@Api(tags = "订单续单管理", description = "订单续单信息管理相关接口，包括查询和审核等操作") @RestController @RequestMapping("/order/continue") public class PlayOrderContinueInfoController { @@ -29,8 +35,12 @@ public class PlayOrderContinueInfoController { /** * 查询订单续单信息列表 */ + @ApiOperation(value = "分页查询续单列表", notes = "分页查询订单续单信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderContinueReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayOrderContinueQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderContinueQueryVo vo) { IPage list = playOrderContinueInfoService.selectPlayByPage(vo); return R.ok(list); } @@ -38,9 +48,14 @@ public class PlayOrderContinueInfoController { /** * 审批续单申申请 */ + @ApiOperation(value = "审批续单申请", notes = "审核店员的续单申请") + @ApiResponses({ + @ApiResponse(code = 200, message = "审批成功"), + @ApiResponse(code = 500, message = "审批失败") + }) //@PreAuthorize("@customSs.hasPermission('order:continue:update')") @PostMapping("/updateReviewState") - public R updateReviewState(@Validated @RequestBody PlayOrderReviewStateEditVo vo) { + public R updateReviewState(@ApiParam(value = "审批信息", required = true) @Validated @RequestBody PlayOrderReviewStateEditVo vo) { playOrderContinueInfoService.updateReviewState(vo); return R.ok("成功"); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderEvaluateInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderEvaluateInfoController.java index ce4727d..672db49 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderEvaluateInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderEvaluateInfoController.java @@ -10,6 +10,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.*; @@ -21,6 +27,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-07 */ +@Api(tags = "订单评价管理", description = "订单评价信息管理相关接口，包括查询、修改和删除等操作") @RestController @RequestMapping("/order/evaluate") public class PlayOrderEvaluateInfoController { @@ -30,8 +37,12 @@ public class PlayOrderEvaluateInfoController { /** * 查询订单评价信息列表 */ + @ApiOperation(value = "分页查询评价列表", notes = "分页查询订单评价信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderEvaluateReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R list(@Validated @RequestBody PlayOrderEvaluateQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderEvaluateQueryVo vo) { IPage list = playOrderEvaluateInfoService.selectByPage(vo); return R.ok(list); } @@ -41,10 +52,15 @@ public class PlayOrderEvaluateInfoController { /** * 修改订单评价信息 */ + @ApiOperation(value = "修改评价状态", notes = "修改订单评价的显示状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) //@PreAuthorize("@customSs.hasPermission('order:evaluate:update')") @Log(title = "修改订单评价状态", businessType = BusinessType.UPDATE) @PostMapping(value = "/updateStatus") - public R update(@Validated @RequestBody PlayOrderEvaluateEditStateVo vo) { + public R update(@ApiParam(value = "评价状态信息", required = true) @Validated @RequestBody PlayOrderEvaluateEditStateVo vo) { PlayOrderEvaluateInfoEntity entity = ConvertUtil.entityToVo(vo, PlayOrderEvaluateInfoEntity.class); boolean success = playOrderEvaluateInfoService.update(entity); if (success) { @@ -56,6 +72,11 @@ public class PlayOrderEvaluateInfoController { /** * 删除订单评价信息 */ + @ApiOperation(value = "删除评价记录", notes = "根据ID批量删除订单评价信息") + @ApiImplicitParam(name = "ids", value = "评价记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) //@PreAuthorize("@customSs.hasPermission('order:evaluate:delete')") @Log(title = "订单评价信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderInfoController.java index c4f359d..f55ef71 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderInfoController.java @@ -17,6 +17,12 @@ import com.starry.common.annotation.Log; import com.starry.common.context.CustomSecurityContextHolder; 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.*; @@ -30,6 +36,7 @@ import java.math.BigDecimal; * @author admin * @since 2024-03-20 */ +@Api(tags = "订单管理", description = "订单信息管理相关接口，包括查询、修改、退款和删除等操作") @RestController @RequestMapping("/order/order/") public class PlayOrderInfoController { @@ -54,8 +61,12 @@ public class PlayOrderInfoController { /** * 分页查询订单列表 */ + @ApiOperation(value = "分页查询订单列表", notes = "分页查询订单信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderInfoEntity.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayOrderInfoQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderInfoQueryVo vo) { return R.ok(orderInfoService.selectOrderInfoPage(vo)); } @@ -63,9 +74,14 @@ public class PlayOrderInfoController { /** * 订单退款 */ + @ApiOperation(value = "订单退款", notes = "处理订单退款操作") + @ApiResponses({ + @ApiResponse(code = 200, message = "退款成功"), + @ApiResponse(code = 500, message = "退款失败，包含详细错误信息") + }) //@PreAuthorize("@customSs.hasPermission('order:order:update')") @PostMapping("/orderRefund") - public R orderRefund(@Validated @RequestBody PlayOrderRefundAddVo vo) { + public R orderRefund(@ApiParam(value = "退款信息", required = true) @Validated @RequestBody PlayOrderRefundAddVo vo) { PlayOrderInfoEntity orderInfo = orderInfoService.selectOrderInfoById(vo.getOrderId()); if (orderInfo.getFinalAmount().compareTo(vo.getRefundAmount()) < 0) { throw new CustomException("退款金额不能大于支付金额"); @@ -101,9 +117,14 @@ public class PlayOrderInfoController { /** * 更换店员 */ + @ApiOperation(value = "更换店员", notes = "修改订单的接单店员") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "操作失败") + }) //@PreAuthorize("@customSs.hasPermission('order:order:update')") @PostMapping("/orderEditAcceptBy") - public R orderEditAcceptBy(@Validated @RequestBody PlayOrderEditAcceptByVo vo) { + public R orderEditAcceptBy(@ApiParam(value = "更换店员信息", required = true) @Validated @RequestBody PlayOrderEditAcceptByVo vo) { orderInfoService.updateStateTo1("2", CustomSecurityContextHolder.getUserId(), vo.getAcceptBy(), vo.getOrderId()); PlayClerkUserInfoEntity clerkUserInfo = playClerkUserInfoService.selectById(vo.getAcceptBy()); PlayOrderInfoEntity orderInfo = orderInfoService.selectOrderInfoById(vo.getOrderId()); @@ -116,9 +137,14 @@ public class PlayOrderInfoController { /** * 后台备注 */ + @ApiOperation(value = "修改后台备注", notes = "修改订单的后台备注信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class), + @ApiResponse(code = 500, message = "操作失败") + }) //@PreAuthorize("@customSs.hasPermission('order:order:update')") @PostMapping("/orderEditBackendRemark") - public R orderEditBackendRemark(@Validated @RequestBody PlayOrderEditBackendRemarkByVo vo) { + public R orderEditBackendRemark(@ApiParam(value = "后台备注信息", required = true) @Validated @RequestBody PlayOrderEditBackendRemarkByVo vo) { PlayOrderInfoEntity orderInfo = orderInfoService.selectOrderInfoById(vo.getOrderId()); PlayOrderInfoEntity updateOrderInfo = new PlayOrderInfoEntity(); updateOrderInfo.setId(orderInfo.getId()); @@ -130,9 +156,14 @@ public class PlayOrderInfoController { /** * 重新抢单 */ + @ApiOperation(value = "重新抢单", notes = "将订单重新设置为抢单状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class), + @ApiResponse(code = 500, message = "操作失败，包含详细错误信息") + }) //@PreAuthorize("@customSs.hasPermission('order:order:update')") @PostMapping("/orderEditRandomSingle") - public R orderEditRandomSingle(@Validated @RequestBody PlayOrderEditRandomSingleVo vo) { + public R orderEditRandomSingle(@ApiParam(value = "重新抢单信息", required = true) @Validated @RequestBody PlayOrderEditRandomSingleVo vo) { PlayOrderInfoEntity orderInfo = orderInfoService.selectOrderInfoById(vo.getOrderId()); if (!"1".equals(orderInfo.getPlaceType())) { throw new CustomException("订单类型错误，无法重新抢单"); @@ -155,6 +186,11 @@ public class PlayOrderInfoController { /** * 根据ID查询订单 */ + @ApiOperation(value = "获取订单详情", notes = "根据ID获取订单详细信息") + @ApiImplicitParam(name = "id", value = "订单ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(orderInfoService.selectById(id)); @@ -164,10 +200,16 @@ public class PlayOrderInfoController { /** * 根据ID修改订单信息 */ + @ApiOperation(value = "修改订单信息", notes = "根据ID修改订单基本信息") + @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('order:order:update')") @Log(title = "修改普通订单", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayOrderInfoEntity orderInfoEntity) { + public R update(@PathVariable String id, @ApiParam(value = "订单信息", required = true) @RequestBody PlayOrderInfoEntity orderInfoEntity) { orderInfoEntity.setId(id); boolean success = orderInfoService.update(orderInfoEntity); if (success) { @@ -180,6 +222,11 @@ public class PlayOrderInfoController { /** * 删除订单 */ + @ApiOperation(value = "删除订单", notes = "根据ID批量删除订单信息") + @ApiImplicitParam(name = "ids", value = "订单ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) //@PreAuthorize("@customSs.hasPermission('order:order:delete')") @Log(title = "删除订单", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRefundInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRefundInfoController.java index bed66c1..d76627c 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRefundInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRefundInfoController.java @@ -8,6 +8,12 @@ import com.starry.admin.modules.order.service.IPlayOrderRefundInfoService; 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.*; @@ -19,6 +25,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-09 */ +@Api(tags = "订单退款管理", description = "订单退款信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/order/refund") public class PlayOrderRefundInfoController { @@ -28,8 +35,12 @@ public class PlayOrderRefundInfoController { /** * 查询订单退款信息列表 */ + @ApiOperation(value = "分页查询退款列表", notes = "分页查询订单退款信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderRefundReturnVo.class, responseContainer = "Page") + }) @PostMapping("/list") - public R list(@Validated @RequestBody PlayOrderRefundQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderRefundQueryVo vo) { IPage list = playOrderRefundInfoService.selectByPage(vo); return R.ok(list); } @@ -37,6 +48,11 @@ public class PlayOrderRefundInfoController { /** * 获取订单退款信息详细信息 */ + @ApiOperation(value = "获取退款详情", notes = "根据ID获取订单退款详细信息") + @ApiImplicitParam(name = "id", value = "退款记录ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderRefundInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playOrderRefundInfoService.selectPlayOrderRefundInfoById(id)); @@ -45,9 +61,14 @@ public class PlayOrderRefundInfoController { /** * 新增订单退款信息 */ + @ApiOperation(value = "新增退款记录", notes = "创建新的订单退款信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @Log(title = "订单退款信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayOrderRefundInfoEntity playOrderRefundInfo) { + public R create(@ApiParam(value = "退款信息", required = true) @RequestBody PlayOrderRefundInfoEntity playOrderRefundInfo) { boolean success = playOrderRefundInfoService.create(playOrderRefundInfo); if (success) { return R.ok(); @@ -58,9 +79,15 @@ public class PlayOrderRefundInfoController { /** * 修改订单退款信息 */ + @ApiOperation(value = "修改退款记录", notes = "根据ID修改订单退款信息") + @ApiImplicitParam(name = "id", value = "退款记录ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @Log(title = "订单退款信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayOrderRefundInfoEntity playOrderRefundInfo) { + public R update(@PathVariable String id, @ApiParam(value = "退款信息", required = true) @RequestBody PlayOrderRefundInfoEntity playOrderRefundInfo) { playOrderRefundInfo.setId(id); boolean success = playOrderRefundInfoService.update(playOrderRefundInfo); if (success) { @@ -72,6 +99,11 @@ public class PlayOrderRefundInfoController { /** * 删除订单退款信息 */ + @ApiOperation(value = "删除退款记录", notes = "根据ID批量删除订单退款信息") + @ApiImplicitParam(name = "ids", value = "退款记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Integer.class) + }) @Log(title = "订单退款信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRewardInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRewardInfoController.java index 58a3fdf..7c03eb3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRewardInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/controller/PlayOrderRewardInfoController.java @@ -7,6 +7,11 @@ import com.starry.admin.modules.order.service.IPlayOrderInfoService; 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.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.PostMapping; import org.springframework.web.bind.annotation.RequestBody; @@ -22,6 +27,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-03-20 */ +@Api(tags = "打赏订单管理", description = "打赏订单信息管理相关接口，包括查询等操作") @RestController @RequestMapping("/order/reward/") public class PlayOrderRewardInfoController { @@ -32,10 +38,17 @@ public class PlayOrderRewardInfoController { private IPlayOrderInfoService orderInfoService; + /** + * 分页查询打赏订单列表 + */ + @ApiOperation(value = "分页查询打赏订单", notes = "分页查询打赏订单信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderRewardReturnVo.class, responseContainer = "Page") + }) //@PreAuthorize("@customSs.hasPermission('order:reward:list')") @Log(title = "查询打赏订单", businessType = BusinessType.INSERT) @PostMapping("/listByPage") - public R queryRewardOrder(@Validated @RequestBody PlayOrderRewardQueryVo vo) { + public R queryRewardOrder(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderRewardQueryVo vo) { IPage page = orderInfoService.selectRewardOrderInfoByPage(vo); return R.ok(page); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintQueryVo.java index b80e174..1a11e99 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintQueryVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.order.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,40 +16,48 @@ import java.util.List; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "订单投诉查询参数", description = "查询订单投诉信息的条件参数") public class PlayOrderComplaintQueryVo extends BasePageEntity { /** * 数据ID */ + @ApiModelProperty(value = "投诉ID", example = "1", notes = "特定投诉记录的ID") private String id; /** * 订单ID */ + @ApiModelProperty(value = "订单ID", example = "1", notes = "被投诉的订单ID") private String orderId; /** * 订单编号 */ + @ApiModelProperty(value = "订单编号", example = "ORDER20240320001", notes = "被投诉的订单编号，支持模糊查询") private String orderNo; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1", notes = "投诉顾客的ID") private String customId; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "被投诉店员的ID") private String clerkId; /** * 微信号码 */ + @ApiModelProperty(value = "微信号码", example = "wx123456", notes = "顾客的微信号码") private String weiChatCode; /** * 投诉时间 */ + @ApiModelProperty(value = "投诉时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "投诉提交时间范围，包含开始和结束时间") private List complaintTime; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintReturnVo.java index b16e585..9305b62 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderComplaintReturnVo.java @@ -3,6 +3,8 @@ package com.starry.admin.modules.order.module.vo; import com.baomidou.mybatisplus.annotation.TableField; import com.starry.admin.common.conf.StringTypeHandler; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.math.BigDecimal; @@ -15,119 +17,142 @@ import java.util.List; * @author admin */ @Data +@ApiModel(value = "订单投诉返回数据", description = "订单投诉信息的返回数据") public class PlayOrderComplaintReturnVo { /** * uuid */ + @ApiModelProperty(value = "投诉ID", example = "1") private String id; /** * 订单ID */ + @ApiModelProperty(value = "订单ID", example = "1") private String orderId; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1") private String customId; /** * 顾客昵称 */ + @ApiModelProperty(value = "顾客昵称", example = "张三") private String customNickname; /** * 顾客头像 */ + @ApiModelProperty(value = "顾客头像", example = "https://example.com/avatar.jpg") private String customAvatar; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1") private String clerkId; /** * 顾客昵称 */ + @ApiModelProperty(value = "店员昵称", example = "小明") private String clerkNickname; /** * 顾客头像 */ + @ApiModelProperty(value = "店员头像", example = "https://example.com/clerk_avatar.jpg") private String clerkAvatar; /** * 投诉人微信号码 */ + @ApiModelProperty(value = "微信号码", example = "wx123456") private String wxChatCode; /** * 投诉内容 */ + @ApiModelProperty(value = "投诉内容", example = "店员服务态度差") private String complaintCon; /** * 投诉时间 */ + @ApiModelProperty(value = "投诉时间", example = "2024-01-01 12:00:00") private Date complaintTime; /** * 图片列表 */ @TableField(typeHandler = StringTypeHandler.class) + @ApiModelProperty(value = "图片列表", example = "['https://example.com/img1.jpg','https://example.com/img2.jpg']") private List images; /** * 数据是否隐藏（0:显示，1:隐藏） */ + @ApiModelProperty(value = "是否隐藏", example = "0", notes = "数据是否隐藏，0:显示，1:隐藏") private String hidden; /** * 订单号 */ + @ApiModelProperty(value = "订单编号", example = "ORDER20240320001") private String orderNo; /** * 下单类型（0：指定单，1：随机单。2：打赏单） */ + @ApiModelProperty(value = "下单类型", example = "0", notes = "0：指定单，1：随机单，2：打赏单") private String placeType; /** * 订单最终金额（支付金额） */ + @ApiModelProperty(value = "支付金额", example = "100.00") private BigDecimal finalAmount; /** * 服务项目ID */ + @ApiModelProperty(value = "商品ID", example = "1") private String commodityId; /** * 项目类型 */ + @ApiModelProperty(value = "商品类型", example = "0", notes = "0:礼物，1：服务") private String commodityType; /** * 项目名称 */ + @ApiModelProperty(value = "商品名称", example = "语音陪聊") private String commodityName; /** * 项目价格 */ + @ApiModelProperty(value = "商品单价", example = "50.00") private BigDecimal commodityPrice; /** * 商品数量 */ + @ApiModelProperty(value = "商品数量", example = "1") private String commodityNumber; /** * 服务时长（文字描述信息,不参与订单计算） */ + @ApiModelProperty(value = "服务时长", example = "30", notes = "服务的时长，单位分钟") private String serviceDuration; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueQueryVo.java index 984a522..f204382 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.order.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,36 +16,43 @@ import java.util.List; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "订单续单查询参数", description = "查询订单续单信息的条件参数") public class PlayOrderContinueQueryVo extends BasePageEntity { + @ApiModelProperty(value = "昵称", example = "小明", notes = "店员或顾客昵称，支持模糊查询") private String nickname; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "申请续单的店员ID") private String clerkId; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1", notes = "相关顾客的ID") private String customId; /** * 订单编号 */ + @ApiModelProperty(value = "订单编号", example = "ORDER20240320001", notes = "相关订单的编号，支持模糊查询") private String orderNo; /** * 审核状态（0:未审核，1:已通过，2:不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0:未审核，1:已通过，2:不通过") private String reviewState; /** * 申请时间 */ + @ApiModelProperty(value = "申请时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "续单申请时间范围，包含开始和结束时间") private List continueTime; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueReturnVo.java index 496935f..9f8d3e1 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderContinueReturnVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.order.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; @@ -15,59 +17,71 @@ import java.util.List; * @since 2024/5/10 14:59 **/ @Data +@ApiModel(value = "订单续单返回数据", description = "订单续单信息的返回数据") public class PlayOrderContinueReturnVo { + @ApiModelProperty(value = "续单ID", example = "1") private String id; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1") private String clerkId; /** * 店员昵称 */ + @ApiModelProperty(value = "店员昵称", example = "小明") private String clerkNickname; /** * 店员昵称 */ + @ApiModelProperty(value = "店员头像", example = "https://example.com/clerk_avatar.jpg") private String clerkAvatar; /** * 店员性别 */ + @ApiModelProperty(value = "店员性别", example = "1", notes = "0:未知,1:男,2:女") private String clerkSex; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1") private String customerId; /** * 用户等级名称 */ + @ApiModelProperty(value = "等级名称", example = "黄金会员") private String levelName; /** * 订单编号 */ + @ApiModelProperty(value = "订单编号", example = "ORDER20240320001") private String orderNo; /** * 下单类型（0：指定单，1：随机单。2：打赏单） */ + @ApiModelProperty(value = "下单类型", example = "0", notes = "0：指定单，1：随机单，2：打赏单") private String placeType; /** * 商品名称 */ + @ApiModelProperty(value = "商品名称", example = "语音陪聊") private String commodityName; /** * 商品单价 */ + @ApiModelProperty(value = "商品单价", example = "50.00") private BigDecimal commodityPrice; /** @@ -75,51 +89,61 @@ public class PlayOrderContinueReturnVo { * * @since 2024/5/8 16:44 **/ + @ApiModelProperty(value = "服务时长", example = "30", notes = "服务的时长，单位分钟") private String serviceDuration; /** * 商品数量 */ + @ApiModelProperty(value = "商品数量", example = "1") private int commodityNumber; /** * 下单金额 */ + @ApiModelProperty(value = "订单金额", example = "100.00") private BigDecimal orderMoney; /** * 订单最终金额（支付金额） */ + @ApiModelProperty(value = "支付金额", example = "100.00") private BigDecimal finalAmount; /** * 申请消息 */ + @ApiModelProperty(value = "申请消息", example = "顾客需要继续服务") private String continueMsg; /** * 截图 */ + @ApiModelProperty(value = "截图列表", example = "['https://example.com/img1.jpg','https://example.com/img2.jpg']") private List images; /** * 是否需要审核，0:不需要，1:需要 */ + @ApiModelProperty(value = "是否需要审核", example = "1", notes = "0:不需要，1:需要") private String reviewedRequired; /** * 审核状态（0:未审核，1:已通过，2:不通过） */ + @ApiModelProperty(value = "审核状态", example = "0", notes = "0:未审核，1:已通过，2:不通过") private String reviewedState; /** * 审核内容 */ + @ApiModelProperty(value = "审核备注", example = "审核通过，可以继续服务") private String reviewedRemark; @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 continueTime; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditAcceptByVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditAcceptByVo.java index 318ace9..3652cea 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditAcceptByVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditAcceptByVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.order.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotNull; @@ -11,6 +13,7 @@ import javax.validation.constraints.NotNull; * @since 2024-03-20 */ @Data +@ApiModel(value = "更换店员参数", description = "更换订单接单店员的请求参数") public class PlayOrderEditAcceptByVo { @@ -18,6 +21,7 @@ public class PlayOrderEditAcceptByVo { * uuid */ @NotNull(message = "orderId不能为空") + @ApiModelProperty(value = "订单ID", required = true, example = "1", notes = "需要更换店员的订单ID") private String orderId; @@ -25,11 +29,13 @@ public class PlayOrderEditAcceptByVo { * 店员ID */ @NotNull(message = "店员不能为空") + @ApiModelProperty(value = "店员ID", required = true, example = "1", notes = "新的接单店员ID") private String acceptBy; /** * 备注 */ + @ApiModelProperty(value = "备注", example = "店员请假，需要更换", notes = "更换店员的原因说明") private String remark; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditBackendRemarkByVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditBackendRemarkByVo.java index 2643f71..d4b187c 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditBackendRemarkByVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditBackendRemarkByVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.order.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.NotNull; * @since 2024-03-20 */ @Data +@ApiModel(value = "修改后台备注参数", description = "修改订单后台备注的请求参数") public class PlayOrderEditBackendRemarkByVo { @@ -19,6 +22,7 @@ public class PlayOrderEditBackendRemarkByVo { * uuid */ @NotNull(message = "orderId不能为空") + @ApiModelProperty(value = "订单ID", required = true, example = "1", notes = "需要修改备注的订单ID") private String orderId; @@ -27,6 +31,7 @@ public class PlayOrderEditBackendRemarkByVo { */ @NotNull(message = "后台备注不能为空") @Length(min = 1, max = 100, message = "后台备注字符长度在1-100个字符之间") + @ApiModelProperty(value = "后台备注", required = true, example = "顾客要求特殊服务", notes = "订单的后台备注内容，1-100字符") private String backendRemark; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditRandomSingleVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditRandomSingleVo.java index 1beedf5..b988881 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditRandomSingleVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEditRandomSingleVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.order.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotNull; @@ -11,6 +13,7 @@ import javax.validation.constraints.NotNull; * @since 2024-03-20 */ @Data +@ApiModel(value = "重新抢单参数", description = "设置订单重新抢单的请求参数") public class PlayOrderEditRandomSingleVo { @@ -18,6 +21,7 @@ public class PlayOrderEditRandomSingleVo { * uuid */ @NotNull(message = "orderId不能为空") + @ApiModelProperty(value = "订单ID", required = true, example = "1", notes = "需要重新抢单的订单ID") private String orderId; @@ -27,11 +31,13 @@ public class PlayOrderEditRandomSingleVo { * @since 2024/5/8 15:31 **/ @NotNull(message = "陪聊性别不能为空") + @ApiModelProperty(value = "店员性别", required = true, example = "2", notes = "抢单店员的性别要求，0:未知;1:男;2:女") private String sex; /** * 陪聊等级 **/ @NotNull(message = "陪聊等级不能为空") + @ApiModelProperty(value = "店员等级", required = true, example = "1", notes = "抢单店员的等级要求") private String levelId; /** @@ -40,6 +46,7 @@ public class PlayOrderEditRandomSingleVo { * @since 2024/5/8 15:28 **/ @NotNull(message = "是否排除下单过的成员不能为空") + @ApiModelProperty(value = "是否排除历史", required = true, example = "1", notes = "是否排除下单过的成员，0:不排除;1:排除") private String excludeHistory; @@ -48,6 +55,7 @@ public class PlayOrderEditRandomSingleVo { * * @since 2024/5/8 15:28 **/ + @ApiModelProperty(value = "订单备注", example = "需要擅长聊天的店员", notes = "订单的备注信息") private String remark; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateEditStateVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateEditStateVo.java index 3ea192a..423cc18 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateEditStateVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateEditStateVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.order.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -12,12 +14,14 @@ import javax.validation.constraints.Pattern; * @author admin */ @Data +@ApiModel(value = "评价状态修改参数", description = "修改订单评价显示状态的请求参数") public class PlayOrderEvaluateEditStateVo { /** * UUID */ @NotBlank(message = "id不能为空") + @ApiModelProperty(value = "评价ID", required = true, example = "1", notes = "需要修改状态的评价ID") private String id; /** @@ -25,5 +29,6 @@ public class PlayOrderEvaluateEditStateVo { */ @NotBlank(message = "是否隐藏不能为空") @Pattern(regexp = "[01]", message = "是否隐藏数据错误,只能位0或者1") + @ApiModelProperty(value = "是否隐藏", required = true, example = "1", notes = "数据是否隐藏，0:显示，1:隐藏") private String hidden; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateQueryVo.java index b52a4f1..0f347fe 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateQueryVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.order.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,40 +16,48 @@ import java.util.List; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "订单评价查询参数", description = "查询订单评价信息的条件参数") public class PlayOrderEvaluateQueryVo extends BasePageEntity { /** * UUID */ + @ApiModelProperty(value = "评价ID", example = "1", notes = "特定评价记录的ID") private String id; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1", notes = "评价顾客的ID") private String customId; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "被评价店员的ID") private String clerkId; /** * 评价内容 */ + @ApiModelProperty(value = "评价内容", example = "服务很好", notes = "评价内容，支持模糊查询") private String evaluateCon; /** * 匿名评价(0:匿名，1:非匿名) */ + @ApiModelProperty(value = "是否匿名", example = "0", notes = "0:匿名，1:非匿名") private String anonymous; /** * 评价时间 */ + @ApiModelProperty(value = "评价时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "评价提交时间范围，包含开始和结束时间") private List evaluateTime; /** * 数据是否隐藏（0:显示，1:隐藏） */ + @ApiModelProperty(value = "是否隐藏", example = "0", notes = "数据是否隐藏，0:显示，1:隐藏") private String hidden; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateReturnVo.java index 55937d8..38f3257 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderEvaluateReturnVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.order.module.vo; import com.fasterxml.jackson.annotation.JsonFormat; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.math.BigDecimal; @@ -13,129 +15,153 @@ import java.util.Date; * @author admin */ @Data +@ApiModel(value = "订单评价返回数据", description = "订单评价信息的返回数据") public class PlayOrderEvaluateReturnVo { /** * uuid */ + @ApiModelProperty(value = "评价ID", example = "1") private String id; /** * 订单ID */ + @ApiModelProperty(value = "订单ID", example = "1") private String orderId; /** * 匿名评价(0:匿名，1:非匿名) */ + @ApiModelProperty(value = "是否匿名", example = "0", notes = "0:匿名，1:非匿名") private String anonymous; /** * 评价类型(0:好评，1差评) */ + @ApiModelProperty(value = "评价类型", example = "0", notes = "0:好评，1:差评") private String evaluateType; /** * 评价等级【1-5星，最低1星，最高5星】 */ + @ApiModelProperty(value = "评价等级", example = "5", notes = "1-5星，最低1星，最高5星") private Integer evaluateLevel; /** * 评价内容 */ + @ApiModelProperty(value = "评价内容", example = "服务很好，店员态度很好") private String evaluateCon; /** * 评价时间 */ - @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") + @ApiModelProperty(value = "评价时间", example = "2024-01-01 12:00:00") private Date evaluateTime; /** * 数据是否隐藏（0:显示，1:隐藏） */ + @ApiModelProperty(value = "是否隐藏", example = "0", notes = "数据是否隐藏，0:显示，1:隐藏") private String hidden; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1") private String customId; /** * 顾客昵称 */ + @ApiModelProperty(value = "顾客昵称", example = "张三") private String customNickname; /** * 顾客头像 */ + @ApiModelProperty(value = "顾客头像", example = "https://example.com/avatar.jpg") private String customAvatar; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1") private String clerkId; /** * 顾客昵称 */ + @ApiModelProperty(value = "店员昵称", example = "小明") private String clerkNickname; /** * 顾客头像 */ + @ApiModelProperty(value = "店员头像", example = "https://example.com/clerk_avatar.jpg") private String clerkAvatar; /** * 点赞数 */ + @ApiModelProperty(value = "点赞数", example = "10") private int likeCount = 10; /** * 订单号 */ + @ApiModelProperty(value = "订单编号", example = "ORDER20240320001") private String orderNo; /** * 下单类型（0：指定单，1：随机单。2：打赏单） */ + @ApiModelProperty(value = "下单类型", example = "0", notes = "0：指定单，1：随机单，2：打赏单") private String placeType; /** * 订单最终金额（支付金额） */ + @ApiModelProperty(value = "支付金额", example = "100.00") private BigDecimal finalAmount; /** * 服务项目ID */ + @ApiModelProperty(value = "商品ID", example = "1") private String commodityId; /** * 项目类型 */ + @ApiModelProperty(value = "商品类型", example = "0", notes = "0:礼物，1：服务") private String commodityType; /** * 项目名称 */ + @ApiModelProperty(value = "商品名称", example = "语音陪聊") private String commodityName; /** * 项目价格 */ + @ApiModelProperty(value = "商品单价", example = "50.00") private BigDecimal commodityPrice; /** * 商品数量 */ + @ApiModelProperty(value = "商品数量", example = "1") private String commodityNumber; /** * 服务时长（文字描述信息,不参与订单计算） */ + @ApiModelProperty(value = "服务时长", example = "30", notes = "服务的时长，单位分钟") private String serviceDuration; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderInfoQueryVo.java index de88644..ba704d3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderInfoQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderInfoQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.order.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -14,16 +16,19 @@ import java.util.List; */ @Data @EqualsAndHashCode(callSuper = false) +@ApiModel(value = "订单查询参数", description = "查询订单信息的条件参数") public class PlayOrderInfoQueryVo extends BasePageEntity { /** * uuid */ + @ApiModelProperty(value = "订单ID", example = "1", notes = "特定订单的ID") private String id; /** * 订单编号 */ + @ApiModelProperty(value = "订单编号", example = "ORDER20240320001", notes = "订单的编号，支持模糊查询") private String orderNo; /** @@ -34,82 +39,98 @@ public class PlayOrderInfoQueryVo extends BasePageEntity { * 3：已完成 * 4：已取消 */ + @ApiModelProperty(value = "订单状态", example = "0", notes = "0：已下单（待接单）;1：已接单（待开始）;2：已开始（服务中）;3：已完成;4：已取消") private String orderStatus; /** * 订单类型【-1:退款订单;0:充值订单；1:提现订单；2:普通订单】 */ + @ApiModelProperty(value = "订单类型", example = "2", notes = "-1:退款订单;0:充值订单;1:提现订单;2:普通订单") private String orderType; /** * 下单类型（-1:其他类型;0:指定单;1:随机单;2:打赏单） */ + @ApiModelProperty(value = "下单类型", example = "0", notes = "-1:其他类型;0:指定单;1:随机单;2:打赏单") private String placeType; /** * 是否是首单【0：不是，1：是】 */ + @ApiModelProperty(value = "是否首单", example = "1", notes = "0：不是，1：是") private String firstOrder; /** * 是否使用优惠券[0:未使用,1:已使用] */ + @ApiModelProperty(value = "是否使用优惠券", example = "1", notes = "0:未使用,1:已使用") private String useCoupon; /** * 是否是客服录入订单[0:不是,1:是] */ + @ApiModelProperty(value = "是否客服录入", example = "0", notes = "0:不是,1:是") private String backendEntry; /** * 支付方式，0：余额支付,1:微信支付,2:支付宝支付 */ + @ApiModelProperty(value = "支付方式", example = "0", notes = "0：余额支付,1:微信支付,2:支付宝支付") private String payMethod; /** * 微信号码 */ + @ApiModelProperty(value = "微信号码", example = "wx123456", notes = "顾客的微信号码") private String weiChatCode; /** * 下单人 */ + @ApiModelProperty(value = "下单人ID", example = "1", notes = "下单顾客的ID") private String purchaserBy; /** * 下单时间 */ + @ApiModelProperty(value = "下单时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "下单时间范围，包含开始和结束时间") private List purchaserTime; /** * 接单人 */ + @ApiModelProperty(value = "接单人ID", example = "1", notes = "接单店员的ID") private String acceptBy; /** * 接单时间 */ + @ApiModelProperty(value = "接单时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "接单时间范围，包含开始和结束时间") private List acceptTime; /** * 开始订单时间（开始服务时间） */ + @ApiModelProperty(value = "开始服务时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "订单开始服务时间范围，包含开始和结束时间") private List startOrderTime; /** * 完成订单时间（开始服务时间） */ + @ApiModelProperty(value = "完成服务时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "订单完成服务时间范围，包含开始和结束时间") private List endOrderTime; /** * 分组ID */ + @ApiModelProperty(value = "分组ID", example = "1", notes = "订单所属分组的ID") private String groupId; + @ApiModelProperty(value = "店员昵称", example = "小明", notes = "接单店员的昵称，支持模糊查询") private String clerkNickName; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundAddVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundAddVo.java index d118e3e..0059edb 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundAddVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundAddVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.order.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; import org.hibernate.validator.constraints.Length; @@ -16,6 +18,7 @@ import java.math.BigDecimal; */ @Data @EqualsAndHashCode(callSuper = false) +@ApiModel(value = "订单退款参数", description = "订单退款操作的请求参数") public class PlayOrderRefundAddVo extends BasePageEntity { @@ -23,6 +26,7 @@ public class PlayOrderRefundAddVo extends BasePageEntity { * uuid */ @NotNull(message = "orderId不能为空") + @ApiModelProperty(value = "订单ID", required = true, example = "1", notes = "需要退款的订单ID") private String orderId; @@ -30,6 +34,7 @@ public class PlayOrderRefundAddVo extends BasePageEntity { * 退款金额 */ @NotNull(message = "退款金额不能为空") + @ApiModelProperty(value = "退款金额", required = true, example = "100.00", notes = "退款的金额，不能大于支付金额") private BigDecimal refundAmount; /** @@ -37,6 +42,7 @@ public class PlayOrderRefundAddVo extends BasePageEntity { */ @NotNull(message = "退款原因不能为空") @Length(min = 1, max = 100, message = "退款原因必须在1-100个字符之间") + @ApiModelProperty(value = "退款原因", required = true, example = "顾客要求退款", notes = "退款的原因说明，1-100字符") private String refundReason; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundQueryVo.java index 94521b4..a3714dc 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.order.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -10,5 +12,15 @@ import lombok.EqualsAndHashCode; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "订单退款查询参数", description = "查询订单退款信息的条件参数") public class PlayOrderRefundQueryVo extends BasePageEntity { + + @ApiModelProperty(value = "订单ID", example = "1", notes = "特定订单的ID") + private String orderId; + + @ApiModelProperty(value = "退款类型", example = "0", notes = "0:全额退款,1:部分退款") + private String refundType; + + @ApiModelProperty(value = "退款状态", example = "1", notes = "退款处理状态") + private String refundStatus; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundReturnVo.java index b8292f2..429a89a 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRefundReturnVo.java @@ -1,8 +1,50 @@ package com.starry.admin.modules.order.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; +import lombok.Data; + +import java.math.BigDecimal; +import java.util.Date; + /** * @author admin * @since 2024/5/9 下午11:10 **/ +@Data +@ApiModel(value = "订单退款返回数据", description = "订单退款信息的返回数据") public class PlayOrderRefundReturnVo { + + @ApiModelProperty(value = "退款ID", example = "1") + private String id; + + @ApiModelProperty(value = "订单ID", example = "1") + private String orderId; + + @ApiModelProperty(value = "订单编号", example = "ORDER20240320001") + private String orderNo; + + @ApiModelProperty(value = "退款金额", example = "100.00") + private BigDecimal refundAmount; + + @ApiModelProperty(value = "退款原因", example = "顾客要求退款") + private String refundReason; + + @ApiModelProperty(value = "退款类型", example = "0", notes = "0:全额退款,1:部分退款") + private String refundType; + + @ApiModelProperty(value = "退款状态", example = "1", notes = "退款处理状态") + private String refundStatus; + + @ApiModelProperty(value = "退款时间", example = "2024-01-01 12:00:00") + private Date refundTime; + + @ApiModelProperty(value = "支付方式", example = "0", notes = "0：余额支付,1:微信支付,2:支付宝支付") + private String payMethod; + + @ApiModelProperty(value = "操作人ID", example = "1") + private String operatorId; + + @ApiModelProperty(value = "操作人名称", example = "管理员") + private String operatorName; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderReviewStateEditVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderReviewStateEditVo.java index b628c4f..e8bbb14 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderReviewStateEditVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderReviewStateEditVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.order.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotBlank; @@ -12,10 +14,12 @@ import javax.validation.constraints.Pattern; * @since 2024/5/10 14:59 **/ @Data +@ApiModel(value = "审批状态修改参数", description = "续单申请审批状态修改的请求参数") public class PlayOrderReviewStateEditVo { @NotBlank(message = "ID不能为空") + @ApiModelProperty(value = "续单ID", required = true, example = "1", notes = "需要审批的续单ID") private String id; /** @@ -23,8 +27,10 @@ public class PlayOrderReviewStateEditVo { */ @NotBlank(message = "审核状态不能为空") @Pattern(regexp = "[12]", message = "审核状态必须为1或2") + @ApiModelProperty(value = "审核状态", required = true, example = "1", notes = "1:已通过，2:不通过") private String reviewState; + @ApiModelProperty(value = "审核备注", example = "审核通过，可以继续服务", notes = "审核意见或备注信息") private String remark; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardQueryVo.java index af88013..4581085 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardQueryVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.order.module.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -13,46 +15,54 @@ import java.util.List; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "打赏订单查询参数", description = "查询打赏订单信息的条件参数") public class PlayOrderRewardQueryVo extends BasePageEntity { /** * UUID */ + @ApiModelProperty(value = "订单ID", example = "1", notes = "特定订单的ID") private String id; /** * 顾客ID */ + @ApiModelProperty(value = "顾客ID", example = "1", notes = "打赏顾客的ID") private String purchaserBy; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "接收打赏的店员ID") private String acceptBy; /** * 打赏留言 */ + @ApiModelProperty(value = "打赏留言", example = "感谢服务", notes = "打赏时的留言内容，支持模糊查询") private String rewardCon; /** * 打赏类型（0:打赏礼物,1:自定义金额） */ + @ApiModelProperty(value = "打赏类型", example = "0", notes = "0:打赏礼物,1:自定义金额") private String rewardType; /** * 礼物ID */ - + @ApiModelProperty(value = "礼物ID", example = "1", notes = "打赏礼物的ID") private String commodityId; /** * 打赏时间 */ + @ApiModelProperty(value = "打赏时间范围", example = "['2024-01-01 00:00:00','2024-12-31 23:59:59']", notes = "打赏时间范围，包含开始和结束时间") private List purchaserTime; /** * 数据是否隐藏（0:显示，1:隐藏） */ + @ApiModelProperty(value = "是否隐藏", example = "0", notes = "数据是否隐藏，0:显示，1:隐藏") private String hidden; diff --git a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardReturnVo.java index db74757..a3d82f3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/order/module/vo/PlayOrderRewardReturnVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.order.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,80 +15,95 @@ import java.time.LocalDateTime; * @author admin */ @Data +@ApiModel(value = "打赏订单返回数据", description = "打赏订单信息的返回数据") public class PlayOrderRewardReturnVo { /** * 订单ID */ + @ApiModelProperty(value = "订单ID", example = "1") private String id; /** * 用户ID */ + @ApiModelProperty(value = "顾客ID", example = "1") private String customId; /** * 用户昵称 */ + @ApiModelProperty(value = "顾客昵称", example = "张三") private String customNickname; /** * 用户头像 */ + @ApiModelProperty(value = "顾客头像", example = "https://example.com/avatar.jpg") private String customAvatar; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1") private String clerkId; /** * 店员昵称 */ + @ApiModelProperty(value = "店员昵称", example = "小明") private String clerkNickname; /** * 店员头像 */ + @ApiModelProperty(value = "店员头像", example = "https://example.com/clerk_avatar.jpg") private String clerkAvatar; /** * 打赏类型 */ + @ApiModelProperty(value = "打赏类型", example = "0", notes = "0:打赏礼物,1:自定义金额") private String rewardType; /** * 订单金额 */ + @ApiModelProperty(value = "订单金额", example = "100.00") private String orderMoney; /** * 支付金额 */ + @ApiModelProperty(value = "支付金额", example = "100.00") private String finalAmount; /** * 商品ID */ + @ApiModelProperty(value = "商品ID", example = "1") private String commodityId; /** * 商品类型[0:礼物，1：服务] */ + @ApiModelProperty(value = "商品类型", example = "0", notes = "0:礼物，1：服务") private String commodityType; /** * 商品名称 */ + @ApiModelProperty(value = "商品名称", example = "爱心礼物") private String commodityName; /** * 商品单价 */ + @ApiModelProperty(value = "商品单价", example = "50.00") private BigDecimal commodityPrice; /** @@ -94,6 +111,7 @@ public class PlayOrderRewardReturnVo { * * @since 2024/5/8 16:44 **/ + @ApiModelProperty(value = "服务时长", example = "30", notes = "服务的时长，单位分钟") private String serviceDuration; @@ -101,6 +119,7 @@ public class PlayOrderRewardReturnVo { /** * 打赏留言 */ + @ApiModelProperty(value = "打赏留言", example = "感谢服务") private String remark; /** @@ -108,6 +127,7 @@ public class PlayOrderRewardReturnVo { */ @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 purchaserTime; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayBalanceDetailsInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayBalanceDetailsInfoController.java index f1e133b..731ad87 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayBalanceDetailsInfoController.java +++ b/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}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelAdminInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelAdminInfoController.java index 6d50837..7594138 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelAdminInfoController.java +++ b/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 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}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelGroupInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelGroupInfoController.java index cbc6140..2c96d79 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelGroupInfoController.java +++ b/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 list = playClerkGroupInfoService.selectByPage(vo); for (PlayPersonnelGroupInfoReturnVo record : list.getRecords()) { List 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) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelUserInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelUserInfoController.java index 1c21e81..d804175 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelUserInfoController.java +++ b/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 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 list = sysUserService.selectAll(); diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelWaiterInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelWaiterInfoController.java index 127b86a..7daa137 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/controller/PlayPersonnelWaiterInfoController.java +++ b/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 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) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditAddInfoVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditAddInfoVo.java index 57c481d..453582e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditAddInfoVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditBaseInfoVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditBaseInfoVo.java index 363ade3..18720f7 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoEditBaseInfoVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoQueryVo.java index 45bb100..2fa61c5 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoQueryVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoReturnVo.java index d7da0c8..df861ca 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelGroupInfoReturnVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoQueryVo.java index 8e2f7d2..f66406b 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoQueryVo.java +++ b/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 addTime; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoReturnVo.java index 235db13..826a402 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelUserInfoReturnVo.java +++ b/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; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditAddInfoVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditAddInfoVo.java index 7fe864d..a1a788e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditAddInfoVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditBaseInfoVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditBaseInfoVo.java index 283a8ff..9e896b6 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoEditBaseInfoVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoQueryVo.java index b401f16..0199bd2 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoQueryVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoReturnVo.java index c670319..a37f996 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/personnel/module/vo/PlayPersonnelWaiterInfoReturnVo.java +++ b/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; diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayClerkGiftInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayClerkGiftInfoController.java index 8f0e50d..8c15fe6 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayClerkGiftInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayClerkGiftInfoController.java @@ -6,6 +6,12 @@ import com.starry.admin.modules.shop.service.IPlayClerkGiftInfoService; 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.web.bind.annotation.*; import javax.annotation.Resource; @@ -16,6 +22,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-05-25 */ +@Api(tags = "店员礼物关联管理", description = "店员和礼物关系管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/play/clerkGift") public class PlayClerkGiftInfoController { @@ -25,8 +32,12 @@ public class PlayClerkGiftInfoController { /** * 查询店员和礼物关系列表 */ + @ApiOperation(value = "查询店员礼物关联列表", notes = "分页查询店员和礼物关系列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkGiftInfoEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayClerkGiftInfoEntity playClerkGiftInfo) { + public R list(@ApiParam(value = "查询条件") PlayClerkGiftInfoEntity playClerkGiftInfo) { IPage list = playClerkGiftInfoService.selectPlayClerkGiftInfoByPage(playClerkGiftInfo); return R.ok(list); } @@ -34,6 +45,11 @@ public class PlayClerkGiftInfoController { /** * 获取店员和礼物关系详细信息 */ + @ApiOperation(value = "获取关联详情", notes = "根据ID获取店员和礼物关系详细信息") + @ApiImplicitParam(name = "id", value = "关联ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkGiftInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playClerkGiftInfoService.selectPlayClerkGiftInfoById(id)); @@ -42,9 +58,14 @@ public class PlayClerkGiftInfoController { /** * 新增店员和礼物关系 */ + @ApiOperation(value = "新增关联信息", notes = "新增店员和礼物关系信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，包含详细错误信息") + }) @Log(title = "店员和礼物关系", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayClerkGiftInfoEntity playClerkGiftInfo) { + public R create(@ApiParam(value = "关联信息", required = true) @RequestBody PlayClerkGiftInfoEntity playClerkGiftInfo) { boolean success = playClerkGiftInfoService.create(playClerkGiftInfo); if (success) { return R.ok(); @@ -55,9 +76,15 @@ public class PlayClerkGiftInfoController { /** * 修改店员和礼物关系 */ + @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 = "修改失败，包含详细错误信息") + }) @Log(title = "店员和礼物关系", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayClerkGiftInfoEntity playClerkGiftInfo) { + public R update(@PathVariable String id, @ApiParam(value = "关联信息", required = true) @RequestBody PlayClerkGiftInfoEntity playClerkGiftInfo) { playClerkGiftInfo.setId(id); boolean success = playClerkGiftInfoService.update(playClerkGiftInfo); if (success) { @@ -69,6 +96,11 @@ public class PlayClerkGiftInfoController { /** * 删除店员和礼物关系 */ + @ApiOperation(value = "删除关联信息", notes = "根据ID批量删除店员和礼物关系信息") + @ApiImplicitParam(name = "ids", value = "关联ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @Log(title = "店员和礼物关系", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCommodityInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCommodityInfoController.java index 629c3f5..5eb9f2f 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCommodityInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCommodityInfoController.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.web.bind.annotation.*; import javax.annotation.Resource; @@ -31,6 +37,7 @@ import java.util.Map; * @author admin * @since 2024-03-31 */ +@Api(tags = "服务项目管理", description = "服务项目信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/shop/commodity") public class PlayCommodityInfoController { @@ -43,6 +50,10 @@ public class PlayCommodityInfoController { @Resource private IPlayCommodityAndLevelInfoService playCommodityAndLevelInfoService; + @ApiOperation(value = "获取表头信息", notes = "获取店员等级表头信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("/getTableName") public R getTableName() { List> result = new ArrayList<>(); @@ -60,6 +71,10 @@ public class PlayCommodityInfoController { /** * 查询服务项目类型 */ + @ApiOperation(value = "查询所有服务项目", notes = "查询所有服务项目类型及其子项目") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("/listAll") public R queryCommodityType() { List> result = new ArrayList<>(); @@ -85,8 +100,13 @@ public class PlayCommodityInfoController { /** * 修改服务项目类型 */ + @ApiOperation(value = "更新服务项目价格", notes = "根据不同店员等级修改服务项目价格") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "更新失败，包含详细错误信息") + }) @PostMapping("/updateInfo") - public R updateInfo(@RequestBody String s) { + public R updateInfo(@ApiParam(value = "价格信息JSON", required = true) @RequestBody String s) { JSONObject jsonObject = JSON.parseObject(s); if (!jsonObject.containsKey("id")) { throw new CustomException("请求参数错误,id不能为空"); @@ -118,6 +138,11 @@ public class PlayCommodityInfoController { /** * 获取服务项目详细信息 */ + @ApiOperation(value = "获取服务项目详情", notes = "根据ID获取服务项目详细信息") + @ApiImplicitParam(name = "id", value = "服务项目ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCommodityInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playCommodityInfoService.selectPlayCommodityInfoById(id)); @@ -126,9 +151,14 @@ public class PlayCommodityInfoController { /** * 新增服务项目 */ + @ApiOperation(value = "新增服务项目", notes = "新增服务项目信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，包含详细错误信息") + }) @Log(title = "服务项目", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCommodityInfoAddVo vo) { + public R create(@ApiParam(value = "服务项目信息", required = true) @RequestBody PlayCommodityInfoAddVo vo) { PlayCommodityInfoEntity entity = ConvertUtil.entityToVo(vo, PlayCommodityInfoEntity.class); boolean success = playCommodityInfoService.create(entity); if (success) { @@ -140,9 +170,15 @@ public class PlayCommodityInfoController { /** * 修改服务项目 */ + @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 = "修改失败，包含详细错误信息") + }) @Log(title = "服务项目", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCommodityInfoEntity playCommodityInfo) { + public R update(@PathVariable String id, @ApiParam(value = "服务项目信息", required = true) @RequestBody PlayCommodityInfoEntity playCommodityInfo) { playCommodityInfo.setId(id); boolean success = playCommodityInfoService.update(playCommodityInfo); if (success) { @@ -154,6 +190,11 @@ public class PlayCommodityInfoController { /** * 删除服务项目 */ + @ApiOperation(value = "删除服务项目", notes = "根据ID批量删除服务项目信息") + @ApiImplicitParam(name = "ids", value = "服务项目ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @Log(title = "服务项目", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponDetailsController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponDetailsController.java index 62c4fa2..43797bd 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponDetailsController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponDetailsController.java @@ -9,6 +9,12 @@ import com.starry.admin.modules.shop.service.IPlayCouponDetailsService; 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.*; @@ -20,6 +26,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-07-04 */ +@Api(tags = "优惠券记录管理", description = "优惠券使用记录管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/shop/couponRecord") public class PlayCouponDetailsController { @@ -30,9 +37,13 @@ public class PlayCouponDetailsController { /** * 查询优惠券详情列表 */ + @ApiOperation(value = "分页查询优惠券记录", notes = "分页查询优惠券使用记录列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCouponDetailsReturnVo.class, responseContainer = "Page") + }) // @PreAuthorize("@customSs.hasPermission('shop:couponDetails:list')") @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayCouponDetailsQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayCouponDetailsQueryVo vo) { IPage list = playCouponDetailsService.selectByPage(vo); return R.ok(list); } @@ -40,6 +51,11 @@ public class PlayCouponDetailsController { /** * 获取优惠券详情详细信息 */ + @ApiOperation(value = "获取优惠券记录详情", notes = "根据ID获取优惠券使用记录详细信息") + @ApiImplicitParam(name = "id", value = "记录ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCouponDetailsEntity.class) + }) // @PreAuthorize("@customSs.hasPermission('shop:couponDetails:query')") @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { @@ -49,10 +65,15 @@ public class PlayCouponDetailsController { /** * 新增优惠券详情 */ + @ApiOperation(value = "新增优惠券记录", notes = "新增优惠券使用记录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，包含详细错误信息") + }) // @PreAuthorize("@customSs.hasPermission('shop:couponDetails:create')") @Log(title = "优惠券详情", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayCouponDetailsEntity playCouponDetails) { + public R create(@ApiParam(value = "优惠券记录信息", required = true) @RequestBody PlayCouponDetailsEntity playCouponDetails) { boolean success = playCouponDetailsService.create(playCouponDetails); if (success) { return R.ok(); @@ -66,8 +87,13 @@ public class PlayCouponDetailsController { * @param vo 优惠券实体信息 * @since 2024/7/4 17:15 **/ + @ApiOperation(value = "更新优惠券使用状态", notes = "批量更新优惠券使用状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "更新失败，包含详细错误信息") + }) @PostMapping("/updateUseState") - public R update(PlayCouponDetailsUpdateUseStateVo vo) { + public R update(@ApiParam(value = "更新状态信息", required = true) PlayCouponDetailsUpdateUseStateVo vo) { for (String couponId : vo.getCouponIds()) { playCouponDetailsService.selectPlayCouponDetailsById(couponId); PlayCouponDetailsEntity entity = new PlayCouponDetailsEntity(); @@ -81,10 +107,16 @@ public class PlayCouponDetailsController { /** * 修改优惠券详情 */ + @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('shop:couponDetails:edit')") @Log(title = "优惠券详情", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCouponDetailsEntity playCouponDetails) { + public R update(@PathVariable String id, @ApiParam(value = "优惠券记录信息", required = true) @RequestBody PlayCouponDetailsEntity playCouponDetails) { playCouponDetails.setId(id); boolean success = playCouponDetailsService.update(playCouponDetails); if (success) { @@ -96,6 +128,11 @@ public class PlayCouponDetailsController { /** * 删除优惠券详情 */ + @ApiOperation(value = "删除优惠券记录", notes = "批量删除优惠券使用记录（逻辑删除）") + @ApiImplicitParam(name = "ids", value = "记录ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) // @PreAuthorize("@customSs.hasPermission('shop:couponDetails:remove')") @Log(title = "优惠券详情", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponInfoController.java index 75f3304..908b180 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayCouponInfoController.java @@ -12,6 +12,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.*; @@ -26,6 +32,7 @@ import java.time.format.DateTimeFormatter; * @author admin * @since 2024-07-04 */ +@Api(tags = "优惠券管理", description = "优惠券信息管理相关接口，包括查询、新增、修改、发放和删除等操作") @RestController @RequestMapping("/shop/coupon") public class PlayCouponInfoController { @@ -41,9 +48,13 @@ public class PlayCouponInfoController { /** * 查询优惠券信息列表 */ + @ApiOperation(value = "分页查询优惠券列表", notes = "分页查询优惠券信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCouponInfoReturnVo.class, responseContainer = "Page") + }) // @PreAuthorize("@customSs.hasPermission('shop:coupon:list')") @PostMapping("/listByPage") - public R list(PlayCouponInfoQueryVo vo) { + public R list(@ApiParam(value = "查询条件") PlayCouponInfoQueryVo vo) { IPage list = playCouponInfoService.selectByPage(vo); return R.ok(list); } @@ -53,8 +64,13 @@ public class PlayCouponInfoController { * * @param vo 优惠券上下架对象 */ + @ApiOperation(value = "更新优惠券上下架状态", notes = "修改优惠券上下架状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "更新失败，包含详细错误信息") + }) @PostMapping("/updateOnLineState") - public R updateOnLineState(@Validated @RequestBody PlayCouponInfoOnLineStateUpdateVo vo) { + public R updateOnLineState(@ApiParam(value = "状态更新信息", required = true) @Validated @RequestBody PlayCouponInfoOnLineStateUpdateVo vo) { playCouponInfoService.selectPlayCouponInfoById(vo.getId()); PlayCouponInfoEntity entity = new PlayCouponInfoEntity(); entity.setId(vo.getId()); @@ -69,8 +85,13 @@ public class PlayCouponInfoController { * * @param vo 优惠券发放对象 */ + @ApiOperation(value = "发放优惠券", notes = "向指定用户发放优惠券") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "发放失败，包含详细错误信息") + }) @PostMapping("/sendCoupon") - public R sendCoupon(@Validated @RequestBody PlayCouponInfoSendVo vo) { + public R sendCoupon(@ApiParam(value = "优惠券发放信息", required = true) @Validated @RequestBody PlayCouponInfoSendVo vo) { PlayCustomUserInfoEntity customUserInfo = playCustomUserInfoService.selectById(vo.getCustomId()); playCouponDetailsService.create(customUserInfo.getId(), customUserInfo.getNickname(), customUserInfo.getLevelId(), vo.getId(), "2", "1"); return R.ok(); @@ -80,6 +101,11 @@ public class PlayCouponInfoController { /** * 获取优惠券信息详细信息 */ + @ApiOperation(value = "获取优惠券详情", notes = "根据ID获取优惠券详细信息") + @ApiImplicitParam(name = "id", value = "优惠券ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCouponInfoEntity.class) + }) // @PreAuthorize("@customSs.hasPermission('shop:coupon:query')") @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { @@ -89,10 +115,15 @@ public class PlayCouponInfoController { /** * 新增优惠券信息 */ + @ApiOperation(value = "新增优惠券", notes = "新增优惠券信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，包含详细错误信息") + }) // @PreAuthorize("@customSs.hasPermission('shop:coupon:create')") @Log(title = "优惠券信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@Validated @RequestBody PlayCouponInfoAddVo vo) { + public R create(@ApiParam(value = "优惠券信息", required = true) @Validated @RequestBody PlayCouponInfoAddVo vo) { PlayCouponInfoEntity entity = ConvertUtil.entityToVo(vo, PlayCouponInfoEntity.class); if ("1".equals(vo.getValidityPeriodType())) { if (vo.getProductiveTime() == null || vo.getProductiveTime().size() != 2) { @@ -132,10 +163,16 @@ public class PlayCouponInfoController { /** * 修改优惠券信息 */ + @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('shop:coupon:edit')") @Log(title = "优惠券信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayCouponInfoEntity playCouponInfo) { + public R update(@PathVariable String id, @ApiParam(value = "优惠券信息", required = true) @RequestBody PlayCouponInfoEntity playCouponInfo) { playCouponInfo.setId(id); boolean success = playCouponInfoService.update(playCouponInfo); if (success) { @@ -147,6 +184,11 @@ public class PlayCouponInfoController { /** * 删除优惠券信息 */ + @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('shop:coupon:remove')") @Log(title = "优惠券信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayGiftInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayGiftInfoController.java index 33c7733..70f8ddf 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayGiftInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayGiftInfoController.java @@ -6,6 +6,13 @@ import com.starry.admin.modules.shop.service.IPlayGiftInfoService; 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.ApiImplicitParams; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.*; import javax.annotation.Resource; @@ -16,6 +23,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-04-25 */ +@Api(tags = "礼物管理", description = "礼物信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/play/giff") public class PlayGiftInfoController { @@ -25,8 +33,12 @@ public class PlayGiftInfoController { /** * 查询礼物列表 */ + @ApiOperation(value = "查询礼物列表", notes = "分页查询礼物信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayGiftInfoEntity.class, responseContainer = "Page") + }) @GetMapping("/list") - public R list(PlayGiftInfoEntity playGiftInfo) { + public R list(@ApiParam(value = "查询条件") PlayGiftInfoEntity playGiftInfo) { IPage list = playGiftInfoService.selectPlayGiftInfoByPage(playGiftInfo); return R.ok(list); } @@ -34,6 +46,11 @@ public class PlayGiftInfoController { /** * 获取礼物详细信息 */ + @ApiOperation(value = "获取礼物详情", notes = "根据ID获取礼物详细信息") + @ApiImplicitParam(name = "id", value = "礼物ID", required = true, paramType = "path", dataType = "String", example = "1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayGiftInfoEntity.class) + }) @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { return R.ok(playGiftInfoService.selectPlayGiftInfoById(id)); @@ -42,9 +59,14 @@ public class PlayGiftInfoController { /** * 新增礼物 */ + @ApiOperation(value = "新增礼物", notes = "新增礼物信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，包含详细错误信息") + }) @Log(title = "礼物", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody PlayGiftInfoEntity playGiftInfo) { + public R create(@ApiParam(value = "礼物信息", required = true) @RequestBody PlayGiftInfoEntity playGiftInfo) { boolean success = playGiftInfoService.create(playGiftInfo); if (success) { return R.ok(); @@ -55,9 +77,15 @@ public class PlayGiftInfoController { /** * 修改礼物 */ + @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 = "修改失败，包含详细错误信息") + }) @Log(title = "礼物", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody PlayGiftInfoEntity playGiftInfo) { + public R update(@PathVariable String id, @ApiParam(value = "礼物信息", required = true) @RequestBody PlayGiftInfoEntity playGiftInfo) { playGiftInfo.setId(id); boolean success = playGiftInfoService.update(playGiftInfo); if (success) { @@ -69,6 +97,11 @@ public class PlayGiftInfoController { /** * 删除礼物 */ + @ApiOperation(value = "删除礼物", notes = "根据ID批量删除礼物信息") + @ApiImplicitParam(name = "ids", value = "礼物ID数组", required = true, paramType = "path", dataType = "String[]", example = "1,2,3") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @Log(title = "礼物", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") public R remove(@PathVariable String[] ids) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopArticleInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopArticleInfoController.java index 6429000..9302991 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopArticleInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopArticleInfoController.java @@ -11,6 +11,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.*; @@ -23,6 +29,7 @@ import java.util.Date; * @author admin * @since 2024-06-05 */ +@Api(tags = "店铺文章管理", description = "店铺文章信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/shop/articleInfo") public class PlayShopArticleInfoController { @@ -33,9 +40,13 @@ public class PlayShopArticleInfoController { /** * 查询店铺文章信息列表 */ + @ApiOperation(value = "分页查询文章列表", notes = "分页查询店铺文章信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayShopArticleInfoEntity.class, responseContainer = "Page") + }) //@PreAuthorize("@customSs.hasPermission('shop:articleInfo:list')") @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayShopArticleInfoQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayShopArticleInfoQueryVo vo) { IPage list = playShopArticleInfoService.selectByPage(vo); return R.ok(list); } @@ -44,9 +55,14 @@ public class PlayShopArticleInfoController { /** * 新增店铺文章信息 */ + @ApiOperation(value = "新增或修改文章", notes = "新增或修改店铺文章信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，包含详细错误信息") + }) //@PreAuthorize("@customSs.hasPermission('shop:articleInfo:add')") @PostMapping("/create") - public R create(@Validated @RequestBody PlayShopArticleInfoAddVo vo) { + public R create(@ApiParam(value = "文章信息", required = true) @Validated @RequestBody PlayShopArticleInfoAddVo vo) { PlayShopArticleInfoEntity entity = ConvertUtil.entityToVo(vo, PlayShopArticleInfoEntity.class); PlayShopArticleInfoEntity entity1 = playShopArticleInfoService.selectByType(entity.getArticleType()); if (entity.getId() == null) { @@ -69,9 +85,14 @@ public class PlayShopArticleInfoController { /** * 修改店铺文章信息 */ + @ApiOperation(value = "更新文章状态", notes = "修改店铺文章状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败，包含详细错误信息") + }) //@PreAuthorize("@customSs.hasPermission('shop:articleInfo:update')") @PostMapping("/handleUpdateState") - public R listByPage(@Validated @RequestBody PlayShopArticleInfoUpdateVo vo) { + public R listByPage(@ApiParam(value = "更新信息", required = true) @Validated @RequestBody PlayShopArticleInfoUpdateVo vo) { PlayShopArticleInfoEntity entity = ConvertUtil.entityToVo(vo, PlayShopArticleInfoEntity.class); playShopArticleInfoService.update(entity); return R.ok(); @@ -80,6 +101,11 @@ public class PlayShopArticleInfoController { /** * 删除店铺文章信息 */ + @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('shop:articleInfo:delete')") @Log(title = "店铺文章信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopCarouselInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopCarouselInfoController.java index 197c2a7..c3e9a9e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopCarouselInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/PlayShopCarouselInfoController.java @@ -12,6 +12,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.*; import org.springframework.web.multipart.MultipartFile; @@ -25,6 +31,7 @@ import java.io.IOException; * @author admin * @since 2024-06-05 */ +@Api(tags = "店铺轮播图管理", description = "店铺首页轮播图信息管理相关接口，包括查询、新增、修改和删除等操作") @RestController @RequestMapping("/shop/carousel") public class PlayShopCarouselInfoController { @@ -37,16 +44,25 @@ public class PlayShopCarouselInfoController { /** * 查询店铺首页轮播列表 */ + @ApiOperation(value = "分页查询轮播图列表", notes = "分页查询店铺首页轮播图信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayShopCarouselInfoEntity.class, responseContainer = "Page") + }) //@PreAuthorize("@customSs.hasPermission('shop:carousel:list')") @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayShopCarouselInfoQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayShopCarouselInfoQueryVo vo) { IPage list = playCarouselInfoService.selectByPage(vo); return R.ok(list); } + @ApiOperation(value = "上传轮播图文件", notes = "上传店铺首页轮播图文件") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功，返回文件地址"), + @ApiResponse(code = 500, message = "上传失败，包含详细错误信息") + }) //@PreAuthorize("@customSs.hasPermission('shop:carousel:add')") @PostMapping("/uploadFile") - public R uploadFile(@RequestParam("file") MultipartFile file) throws IOException { + public R uploadFile(@ApiParam(value = "轮播图文件", required = true) @RequestParam("file") MultipartFile file) throws IOException { String fileAddress = ossFileService.upload(file.getInputStream(), SecurityUtils.getTenantId(), file.getOriginalFilename()); return R.ok(fileAddress); } @@ -55,9 +71,14 @@ public class PlayShopCarouselInfoController { /** * 新增页轮播列表 */ + @ApiOperation(value = "新增轮播图", notes = "新增店铺首页轮播图信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，包含详细错误信息") + }) //@PreAuthorize("@customSs.hasPermission('shop:carousel:add')") @PostMapping("/create") - public R create(@Validated @RequestBody PlayShopCarouselInfoAddVo vo) { + public R create(@ApiParam(value = "轮播图信息", required = true) @Validated @RequestBody PlayShopCarouselInfoAddVo vo) { PlayShopCarouselInfoEntity entity = ConvertUtil.entityToVo(vo, PlayShopCarouselInfoEntity.class); playCarouselInfoService.create(entity); return R.ok(); @@ -67,9 +88,14 @@ public class PlayShopCarouselInfoController { /** * 修改页轮播状态 */ + @ApiOperation(value = "更新轮播图状态", notes = "修改店铺首页轮播图状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败，包含详细错误信息") + }) //@PreAuthorize("@customSs.hasPermission('shop:carousel:update')") @PostMapping("/handleUpdateState") - public R listByPage(@Validated @RequestBody PlayShopCarouselInfoUpdateStateVo vo) { + public R listByPage(@ApiParam(value = "更新信息", required = true) @Validated @RequestBody PlayShopCarouselInfoUpdateStateVo vo) { PlayShopCarouselInfoEntity entity = ConvertUtil.entityToVo(vo, PlayShopCarouselInfoEntity.class); playCarouselInfoService.update(entity); return R.ok(); @@ -78,6 +104,11 @@ public class PlayShopCarouselInfoController { /** * 删除店铺首页轮播 */ + @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('shop:carousel:delete')") @Log(title = "店铺首页轮播", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/ShopUiSettingController.java b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/ShopUiSettingController.java index b26a4e7..e9a512e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/shop/controller/ShopUiSettingController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/shop/controller/ShopUiSettingController.java @@ -3,7 +3,11 @@ package com.starry.admin.modules.shop.controller; import com.starry.admin.modules.shop.module.entity.ShopUiSettingEntity; import com.starry.admin.modules.shop.service.IShopUiSettingService; 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 javax.annotation.Resource; @@ -20,6 +24,7 @@ import org.springframework.web.bind.annotation.RestController; * @author admin * @since 2025-06-11 */ +@Api(tags = "店铺UI设置", description = "店铺UI设置相关接口，包括查询和修改操作") @RestController @RequestMapping("/play/setting") public class ShopUiSettingController { @@ -30,6 +35,10 @@ public class ShopUiSettingController { /** * 获取店铺设置详细信息 */ + @ApiOperation(value = "获取店铺设置信息", notes = "获取店铺UI设置详细信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = ShopUiSettingEntity.class) + }) @GetMapping(value = "/info") public R getInfo() { return R.ok(shopUiSettingService.selectShopUiSettingInfo()); @@ -38,8 +47,13 @@ public class ShopUiSettingController { /** * 修改店铺设置 */ + @ApiOperation(value = "修改店铺设置", notes = "修改店铺UI设置信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败，包含详细错误信息") + }) @PostMapping(value = "/update") - public R update(@RequestBody ShopUiSettingEntity shopUiSetting) { + public R update(@ApiParam(value = "店铺UI设置信息", required = true) @RequestBody ShopUiSettingEntity shopUiSetting) { boolean success = shopUiSettingService.update(shopUiSetting); if (success) { return R.ok(); diff --git a/play-admin/src/main/java/com/starry/admin/modules/statistics/controller/PlayClerkPerformanceController.java b/play-admin/src/main/java/com/starry/admin/modules/statistics/controller/PlayClerkPerformanceController.java index 1e7fb03..2a45926 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/statistics/controller/PlayClerkPerformanceController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/statistics/controller/PlayClerkPerformanceController.java @@ -13,6 +13,11 @@ import com.starry.admin.modules.statistics.module.vo.PlayClerkPerformanceInfoQue import com.starry.admin.modules.statistics.module.vo.PlayClerkPerformanceInfoReturnVo; import com.starry.admin.modules.statistics.service.IPlayClerkPerformanceService; 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.PostMapping; import org.springframework.web.bind.annotation.RequestBody; @@ -34,6 +39,7 @@ import java.util.stream.Collectors; * @author admin * @since 2024/6/15 下午3:15 **/ +@Api(tags = "店员业绩统计", description = "店员业绩统计相关接口，包括按日期、月份查询等操作") @RestController @RequestMapping("/statistics/performance") public class PlayClerkPerformanceController { @@ -54,8 +60,12 @@ public class PlayClerkPerformanceController { private IPlayClerkPerformanceService playClerkPerformanceService; + @ApiOperation(value = "分页查询店员业绩", notes = "分页查询店员业绩统计信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkPerformanceInfoReturnVo.class, responseContainer = "Page") + }) @PostMapping("/listByPage") - public R listByPage(@Validated @RequestBody PlayClerkPerformanceInfoQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkPerformanceInfoQueryVo vo) { IPage page = clerkUserInfoService.selectByPage(vo); IPage voPage = page.convert(u -> { List clerkLevelInfoEntity = playClerkLevelInfoService.selectAll(); @@ -70,8 +80,12 @@ public class PlayClerkPerformanceController { } + @ApiOperation(value = "按日查询业绩", notes = "按日期查询店员业绩统计信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PostMapping("/listByTime") - public R listByTime(@Validated @RequestBody PlayClerkPerformanceInfoQueryVo vo) { + public R listByTime(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkPerformanceInfoQueryVo vo) { //时间范围 List dates = getDateRangeByDay(vo.getEndOrderTime().get(0), vo.getEndOrderTime().get(1)); //指定时间内所有订单 @@ -89,8 +103,12 @@ public class PlayClerkPerformanceController { } + @ApiOperation(value = "按月查询业绩", notes = "按月份查询店员业绩统计信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PostMapping("/listByMonth") - public R listByMonth(@Validated @RequestBody PlayClerkPerformanceInfoQueryVo vo) { + public R listByMonth(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkPerformanceInfoQueryVo vo) { String startTime = LocalDate.of(Integer.parseInt(vo.getEndOrderTime().get(0).split("-")[0]), Integer.parseInt(vo.getEndOrderTime().get(0).split("-")[1]), 1).toString() + " 00:00:00"; LocalDate endDate = LocalDate.of(Integer.parseInt(vo.getEndOrderTime().get(1).split("-")[0]), Integer.parseInt(vo.getEndOrderTime().get(1).split("-")[1]), 1); String endTime = endDate.with(TemporalAdjusters.lastDayOfMonth()) + " 23:59:59"; diff --git a/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoQueryVo.java index 1d749bb..367f267 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.statistics.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,37 +14,44 @@ import java.util.List; **/ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "店员业绩查询参数", description = "查询店员业绩统计信息的条件参数") public class PlayClerkPerformanceInfoQueryVo extends BasePageEntity { /** * 分组ID */ + @ApiModelProperty(value = "分组ID", example = "1", notes = "店员所属分组ID") private String groupId; /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1", notes = "店员ID") private String clerkId; /** * 店员性别 */ + @ApiModelProperty(value = "店员性别", example = "1", notes = "店员性别，1男2女") private String sex; /** * 店员上架状态 */ + @ApiModelProperty(value = "上架状态", example = "1", notes = "店员上架状态，1上架0下架") private String listingState; /** * 订单状态ID */ + @ApiModelProperty(value = "订单状态", example = "[\"1\",\"2\"]", notes = "订单状态ID列表") private List orderStatus; /** * 完成订单时间 */ + @ApiModelProperty(value = "订单时间范围", example = "[\"2024-01-01 00:00:00\",\"2024-12-31 23:59:59\"]", notes = "订单开始和结束时间") private List endOrderTime; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoReturnVo.java b/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoReturnVo.java index e0b4c70..22bae1e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoReturnVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/statistics/module/vo/PlayClerkPerformanceInfoReturnVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.statistics.module.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.math.BigDecimal; @@ -9,124 +11,152 @@ import java.math.BigDecimal; * @since 2024/6/10 下午8:58 **/ @Data +@ApiModel(value = "店员业绩返回数据", description = "店员业绩统计信息的返回数据") public class PlayClerkPerformanceInfoReturnVo { /** * 店员ID */ + @ApiModelProperty(value = "店员ID", example = "1") private String clerkId; /** * 店员昵称 */ + @ApiModelProperty(value = "店员昵称", example = "张三") private String clerkNickname; /** * 店员昵称 */ + @ApiModelProperty(value = "店员性别", example = "1", notes = "1男2女") private String clerkSex; /** * 分组名称 */ + @ApiModelProperty(value = "分组名称", example = "销售组") private String groupName = ""; /** * 分组名称 */ + @ApiModelProperty(value = "等级名称", example = "初级") private String levelName = ""; /** * 在线时长 */ + @ApiModelProperty(value = "在线时长", example = "120", notes = "单位：分钟") private Integer onlineDuration = 0; /** * 订单总数 */ + @ApiModelProperty(value = "订单总数", example = "10") private Integer orderNumber = 0; /** * 首单数 */ + @ApiModelProperty(value = "首单数", example = "5") private Integer orderFirstNumber = 0; /** * 续单数 */ + @ApiModelProperty(value = "续单数", example = "5") private Integer orderContinueNumber = 0; /** * 退款单数 */ + @ApiModelProperty(value = "退款单数", example = "1") private Integer orderRefundNumber = 0; /** * 超时未接单数 */ + @ApiModelProperty(value = "超时未接单数", example = "1") private Integer ordersExpiredNumber = 0; /** * 订单金额 */ + @ApiModelProperty(value = "订单金额", example = "1000.00") private BigDecimal orderMoney; /** * 订单最终金额（支付金额） */ + @ApiModelProperty(value = "支付金额", example = "900.00", notes = "订单最终金额（支付金额）") private BigDecimal finalAmount = BigDecimal.ZERO; /** * 充值金额 */ + @ApiModelProperty(value = "充值金额", example = "500.00") private BigDecimal rechargeAmount = BigDecimal.ZERO; /** * 首单金额 */ + @ApiModelProperty(value = "首单金额", example = "300.00") private BigDecimal orderFirstAmount = BigDecimal.ZERO; /** * 续单金额 */ + @ApiModelProperty(value = "续单金额", example = "600.00") private BigDecimal orderTotalAmount = BigDecimal.ZERO; /** * 打赏金额 */ + @ApiModelProperty(value = "打赏金额", example = "100.00") private BigDecimal orderRewardAmount = BigDecimal.ZERO; /** * 退款金额 */ + @ApiModelProperty(value = "退款金额", example = "50.00") private BigDecimal orderRefundAmount = BigDecimal.ZERO; /** * 用户数 */ + @ApiModelProperty(value = "用户数", example = "8") private Integer customNumber = 0; /** * 连续用户数 */ - private final Integer continuousCustomNumber = 0; + @ApiModelProperty(value = "连续用户数", example = "3") + private final Integer continuousCustomNumber = 0; /** * 续单比例 */ + @ApiModelProperty(value = "续单比例", example = "0.5", notes = "续单数/订单总数") private final BigDecimal orderContinueProportion = BigDecimal.ZERO; /** * 订单平均价格 */ + @ApiModelProperty(value = "订单平均价格", example = "90.00") private final BigDecimal averageUnitPrice = BigDecimal.ZERO; /** * 续费率 */ + @ApiModelProperty(value = "续费率", example = "0.6") private BigDecimal orderContinueRechargeProportion = BigDecimal.ZERO; /** * 退单率 */ + @ApiModelProperty(value = "退单率", example = "0.1") private BigDecimal orderChargebackProportion = BigDecimal.ZERO; /** * 续客率 */ + @ApiModelProperty(value = "续客率", example = "0.4") private BigDecimal continuousCustomProportion = BigDecimal.ZERO; /** * 店员预计收入 */ + @ApiModelProperty(value = "预计收入", example = "450.00") private BigDecimal estimatedRevenue = BigDecimal.ZERO; /** * 统计时间 */ + @ApiModelProperty(value = "统计时间", example = "2024-06-01") private String performanceDate; diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/AdministrativeAreaDictInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/AdministrativeAreaDictInfoController.java index 58c3755..280ee1e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/AdministrativeAreaDictInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/AdministrativeAreaDictInfoController.java @@ -2,6 +2,10 @@ package com.starry.admin.modules.system.controller; import com.starry.admin.modules.system.service.ISysAdministrativeAreaDictInfoService; import com.starry.common.result.R; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -15,6 +19,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-04-03 */ +@Api(tags = "行政区域字典", description = "行政区域字典信息相关接口") @RestController @RequestMapping("/sys/area") public class AdministrativeAreaDictInfoController { @@ -24,6 +29,10 @@ public class AdministrativeAreaDictInfoController { /** * 查询省/市行政区域代码 */ + @ApiOperation(value = "获取行政区域树", notes = "查询省/市行政区域代码的树形结构") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('play:info:list')") @GetMapping("/tree") public R list() throws Exception { diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/CacheController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/CacheController.java index 1d9e187..f4d1240 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/CacheController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/CacheController.java @@ -5,6 +5,11 @@ import com.starry.admin.modules.system.module.entity.Cache; import com.starry.common.constant.CacheConstants; import com.starry.common.result.R; import com.starry.common.utils.StringUtils; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiImplicitParam; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.data.redis.connection.RedisServerCommands; import org.springframework.data.redis.core.RedisCallback; import org.springframework.data.redis.core.RedisTemplate; @@ -19,6 +24,7 @@ import java.util.*; * 缓存监控 * @since 2022/10/17 */ +@Api(tags = "缓存监控", description = "系统缓存监控相关接口") @RestController @RequestMapping("/monitor/cache") public class CacheController { @@ -33,6 +39,10 @@ public class CacheController { CACHES.add(new Cache(CacheConstants.CAPTCHA_CODE_KEY, "验证码")); } + @ApiOperation(value = "获取缓存信息", notes = "获取Redis服务器信息和命令统计") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class) + }) @PreAuthorize("@customSs.hasPermission('monitor:cache:list')") @GetMapping() public R getInfo() throws Exception { @@ -55,12 +65,21 @@ public class CacheController { return R.ok(result); } + @ApiOperation(value = "获取缓存名称", notes = "获取系统中所有缓存分类名称") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Cache.class, responseContainer = "List") + }) @PreAuthorize("@customSs.hasPermission('monitor:cache:list')") @GetMapping("/getNames") public R cache() { return R.ok(CACHES); } + @ApiOperation(value = "获取缓存键名", notes = "根据缓存名称获取对应的所有缓存键") + @ApiImplicitParam(name = "cacheName", value = "缓存名称", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class, responseContainer = "Set") + }) @PreAuthorize("@customSs.hasPermission('monitor:cache:list')") @GetMapping("/getKeys/{cacheName}") public R getCacheKeys(@PathVariable String cacheName) { @@ -68,6 +87,10 @@ public class CacheController { return R.ok(cacheKeys); } + @ApiOperation(value = "获取缓存值", notes = "根据缓存名称和键名获取缓存值") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Cache.class) + }) @PreAuthorize("@customSs.hasPermission('monitor:cache:list')") @GetMapping("/getValue/{cacheName}/{cacheKey}") public R getCacheValue(@PathVariable String cacheName, @PathVariable String cacheKey) { @@ -76,6 +99,11 @@ public class CacheController { return R.ok(cache); } + @ApiOperation(value = "清除缓存名称", notes = "清除指定缓存名称下的所有缓存") + @ApiImplicitParam(name = "cacheName", value = "缓存名称", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('monitor:cache:list')") @DeleteMapping("/clearCacheName/{cacheName}") public R clearCacheName(@PathVariable String cacheName) { @@ -84,6 +112,11 @@ public class CacheController { return R.ok(); } + @ApiOperation(value = "清除缓存键", notes = "清除指定的缓存键") + @ApiImplicitParam(name = "cacheKey", value = "缓存键", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('monitor:cache:list')") @DeleteMapping("/clearCacheKey/{cacheKey}") public R clearCacheKey(@PathVariable String cacheKey) { @@ -91,6 +124,10 @@ public class CacheController { return R.ok(); } + @ApiOperation(value = "清除所有缓存", notes = "清除系统中所有缓存数据") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('monitor:cache:list')") @DeleteMapping("/clearCacheAll") public R clearCacheAll() { diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/LoginController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/LoginController.java index 54ebd04..c35b6b4 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/LoginController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/LoginController.java @@ -14,6 +14,9 @@ import com.starry.common.redis.CaptchaService; 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.apache.commons.lang3.StringUtils; import org.springframework.beans.factory.annotation.Value; import org.springframework.web.bind.annotation.GetMapping; @@ -30,7 +33,7 @@ import java.util.Set; /** * @author admin */ -@Api(tags = "登录管理") +@Api(tags = "登录管理", description = "用户登录及认证相关接口") @RestController public class LoginController { @@ -47,9 +50,13 @@ public class LoginController { @Resource private JwtToken jwtToken; - @ApiOperation(value = "登录") + @ApiOperation(value = "旧版登录", notes = "用户登录接口，返回Token") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class), + @ApiResponse(code = 500, message = "登录失败，用户名或密码错误") + }) @PostMapping(value = "old-login") - public R login(@RequestBody LoginVo loginVo) { + public R login(@ApiParam(value = "登录信息", required = true) @RequestBody LoginVo loginVo) { // 只有开启了验证码功能才需要验证 if (needAuthCode) { String msg = captchaService.checkImageCode(loginVo.getNonceStr(), loginVo.getValue()); @@ -67,7 +74,11 @@ public class LoginController { return R.ok(tokenMap); } - @ApiOperation(value = "登录后获取用户信息") + @ApiOperation(value = "获取用户信息", notes = "登录后获取当前用户的详细信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class), + @ApiResponse(code = 401, message = "未授权") + }) @GetMapping("get-info") public R getInfo() { SysUserEntity user = SecurityUtils.getLoginUser().getUser(); @@ -87,7 +98,10 @@ public class LoginController { return R.ok(data); } - @ApiOperation(value = "登录后获取路由信息") + @ApiOperation(value = "获取路由信息", notes = "登录后获取当前用户的菜单路由信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = RouterVo.class, responseContainer = "List") + }) @GetMapping("get-routers") public R getRoutes() { List menus = menuService.selectMenuTreeByUserId(SecurityUtils.getUserId()); @@ -95,9 +109,13 @@ public class LoginController { return R.ok(routerVos); } - @ApiOperation(value = "登录") + @ApiOperation(value = "新版登录", notes = "新版用户登录接口，支持租户") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class), + @ApiResponse(code = 500, message = "登录失败，验证码错误或用户名密码错误") + }) @PostMapping(value = "login") - public R newLogin(@RequestBody LoginVo loginVo) { + public R newLogin(@ApiParam(value = "登录信息", required = true) @RequestBody LoginVo loginVo) { // 只有开启了验证码功能才需要验证 if (needAuthCode) { String msg = captchaService.checkImageCode(loginVo.getNonceStr(), loginVo.getValue()); diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/ServerController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/ServerController.java index 0a36c8e..e05a0dd 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/ServerController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/ServerController.java @@ -3,6 +3,10 @@ package com.starry.admin.modules.system.controller; import com.starry.admin.modules.system.module.entity.Server; import com.starry.common.result.R; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -13,10 +17,15 @@ import org.springframework.web.bind.annotation.RestController; * 服务器监控 * @since 2022/10/17 */ +@Api(tags = "服务器监控", description = "服务器状态监控相关接口") @RestController @RequestMapping("/monitor/server") public class ServerController { + @ApiOperation(value = "获取服务器信息", notes = "获取服务器运行状态、CPU、内存等信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Server.class) + }) @PreAuthorize("@customSs.hasPermission('monitor:server:list')") @GetMapping() public R getInfo() throws Exception { diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDeptController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDeptController.java index f6ebcfc..ffa66c6 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDeptController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDeptController.java @@ -6,7 +6,12 @@ import com.starry.admin.modules.system.module.entity.SysDeptEntity; import com.starry.admin.modules.system.service.SysDeptService; import com.starry.common.constant.UserConstants; 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.security.access.prepost.PreAuthorize; import org.springframework.web.bind.annotation.*; @@ -22,6 +27,7 @@ import java.util.List; * @author admin * @since 2022-07-12 */ +@Api(tags = "部门管理", description = "系统部门相关接口") @RestController @RequestMapping("/ucenter/dept") public class SysDeptController { @@ -29,18 +35,25 @@ public class SysDeptController { @Resource private SysDeptService deptService; - @ApiOperation("获取部门列表") + @ApiOperation(value = "获取部门列表", notes = "根据条件查询部门列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDeptEntity.class, responseContainer = "List") + }) @PreAuthorize("@customSs.hasPermission('system:dept:list')") @GetMapping("/list") - public R list(SysDeptEntity dept) { + public R list(@ApiParam(value = "查询条件") SysDeptEntity dept) { List depts = deptService.selectDeptList(dept); return R.ok(depts); } - @ApiOperation("添加部门") + @ApiOperation(value = "添加部门", notes = "创建新的部门") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，部门名称已存在") + }) @PreAuthorize("@customSs.hasPermission('system:dept:create')") @PostMapping("/create") - public R creat(@RequestBody SysDeptEntity dept) { + public R creat(@ApiParam(value = "部门信息", required = true) @RequestBody SysDeptEntity dept) { if (UserConstants.NOT_UNIQUE.equals(deptService.checkDeptNameUnique(dept))) { return R.error("新增部门'" + dept.getDeptName() + "'失败，部门名称已存在"); } @@ -51,10 +64,15 @@ public class SysDeptController { return R.error("添加失败"); } - @ApiOperation("修改部门") + @ApiOperation(value = "修改部门", notes = "根据ID修改部门信息") + @ApiImplicitParam(name = "id", value = "部门ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败，部门名称已存在或上级部门不能是自己") + }) @PreAuthorize("@customSs.hasPermission('system:dept:edit')") @PostMapping("/update/{id}") - public R update(@PathVariable Long id, @RequestBody SysDeptEntity dept) { + public R update(@PathVariable Long id, @ApiParam(value = "部门信息", required = true) @RequestBody SysDeptEntity dept) { dept.setDeptId(id); if (UserConstants.NOT_UNIQUE.equals(deptService.checkDeptNameUnique(dept))) { return R.error("修改部门'" + dept.getDeptName() + "'失败，部门名称已存在"); @@ -68,7 +86,12 @@ public class SysDeptController { return R.error("修改失败"); } - @ApiOperation("删除部门") + @ApiOperation(value = "删除部门", notes = "根据ID删除部门") + @ApiImplicitParam(name = "id", value = "部门ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "删除失败，存在下级部门") + }) @PreAuthorize("@customSs.hasPermission('system:dept:delete')") @PostMapping(value = "/delete/{id}") public R delete(@PathVariable("id") Long deptId) { @@ -82,15 +105,22 @@ public class SysDeptController { return R.error("删除失败"); } - @ApiOperation("获取部门下拉树列表") + @ApiOperation(value = "获取部门下拉树列表", notes = "获取部门的树形结构数据") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = TreeSelect.class, responseContainer = "List") + }) @GetMapping("/treeselect") - public R treeselect(SysDeptEntity dept) { + public R treeselect(@ApiParam(value = "查询条件") SysDeptEntity dept) { List list = deptService.selectDeptList(dept); List treeList = deptService.buildDeptTreeSelect(list); return R.ok(treeList); } - @ApiOperation("根据id获取详细信息") + @ApiOperation(value = "获取部门详情", notes = "根据部门ID获取详细信息") + @ApiImplicitParam(name = "deptId", value = "部门ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDeptEntity.class) + }) @GetMapping(value = "/{deptId}") public R getInfo(@PathVariable Long deptId) { return R.ok(deptService.getById(deptId)); diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictController.java index 4cb4546..cd4a6d8 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictController.java @@ -7,6 +7,13 @@ import com.starry.admin.modules.system.vo.SysDictVo; 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.ApiImplicitParams; +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.web.bind.annotation.*; @@ -19,6 +26,7 @@ import java.util.List; * * @author admin */ +@Api(tags = "字典类型管理", description = "系统字典类型相关接口") @RestController @RequestMapping("/system/dict") public class SysDictController { @@ -28,9 +36,13 @@ public class SysDictController { /** * 查询字典表列表 */ + @ApiOperation(value = "查询字典类型列表", notes = "分页查询字典类型列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDictEntity.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('system:dict:list')") @GetMapping("/list") - public R list(SysDictVo dictVo) { + public R list(@ApiParam(value = "查询条件") SysDictVo dictVo) { Page list = xlDictService.selectXlDictList(dictVo); return R.ok(list); } @@ -39,6 +51,11 @@ public class SysDictController { /** * 获取字典表详细信息 */ + @ApiOperation(value = "获取字典类型详情", notes = "根据ID获取字典类型详细信息") + @ApiImplicitParam(name = "dictId", value = "字典ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDictEntity.class) + }) @PreAuthorize("@customSs.hasPermission('system:dict:query')") @GetMapping(value = "/{dictId}") public R getInfo(@PathVariable("dictId") Long dictId) { @@ -48,10 +65,15 @@ public class SysDictController { /** * 新增字典表 */ + @ApiOperation(value = "新增字典类型", notes = "创建新的字典类型") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @PreAuthorize("@customSs.hasPermission('system:dict:create')") @Log(title = "字典表", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody SysDictEntity sysDictEntity) { + public R create(@ApiParam(value = "字典类型信息", required = true) @RequestBody SysDictEntity sysDictEntity) { boolean success = xlDictService.create(sysDictEntity); if (success) { return R.ok(); @@ -62,10 +84,16 @@ public class SysDictController { /** * 修改字典表 */ + @ApiOperation(value = "修改字典类型", notes = "根据ID修改字典类型") + @ApiImplicitParam(name = "dictId", value = "字典ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PreAuthorize("@customSs.hasPermission('system:dict:edit')") @Log(title = "字典表", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{dictId}") - public R update(@PathVariable Long dictId, @RequestBody SysDictEntity sysDictEntity) { + public R update(@PathVariable Long dictId, @ApiParam(value = "字典类型信息", required = true) @RequestBody SysDictEntity sysDictEntity) { sysDictEntity.setDictId(dictId); boolean success = xlDictService.update(sysDictEntity); if (success) { @@ -77,6 +105,11 @@ public class SysDictController { /** * 删除字典表 */ + @ApiOperation(value = "删除字典类型", notes = "根据ID批量删除字典类型") + @ApiImplicitParam(name = "dictIds", value = "字典ID数组", required = true, dataType = "Long[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('system:dict:remove')") @Log(title = "字典表", businessType = BusinessType.DELETE) @DeleteMapping("/{dictIds}") @@ -84,6 +117,10 @@ public class SysDictController { return R.ok(xlDictService.deleteXlDictByDictIds(dictIds)); } + @ApiOperation(value = "获取字典选择列表", notes = "获取所有字典类型的下拉选择数据") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDictEntity.class, responseContainer = "List") + }) @GetMapping("/optionselect") public R optionselect() { List list = xlDictService.selectDictTypeAll(); @@ -93,6 +130,10 @@ public class SysDictController { /** * 刷新字典缓存 */ + @ApiOperation(value = "刷新字典缓存", notes = "清除并重新加载字典缓存") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('system:dict:remove')") @Log(title = "字典类型", businessType = BusinessType.CLEAN) @DeleteMapping("/refreshCache") diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictDataController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictDataController.java index 16bacc6..a00e96e 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictDataController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysDictDataController.java @@ -7,6 +7,12 @@ import com.starry.admin.modules.system.vo.SysDictDataVo; 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.security.access.prepost.PreAuthorize; import org.springframework.web.bind.annotation.*; @@ -20,6 +26,7 @@ import java.util.List; * * @author admin */ +@Api(tags = "字典数据管理", description = "系统字典数据项相关接口") @RestController @RequestMapping("/system/dict/data") public class SysDictDataController { @@ -29,9 +36,13 @@ public class SysDictDataController { /** * 查询字典数据表列表 */ + @ApiOperation(value = "查询字典数据列表", notes = "根据条件查询字典数据项列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDictDataEntity.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('system:dict:list')") @GetMapping("/list") - public R list(SysDictDataVo sysDictDataEntity) { + public R list(@ApiParam(value = "查询条件") SysDictDataVo sysDictDataEntity) { return R.ok(xlDictDataService.selectXlDictDataList(sysDictDataEntity)); } @@ -39,6 +50,11 @@ public class SysDictDataController { /** * 获取字典数据表详细信息 */ + @ApiOperation(value = "获取字典数据详情", notes = "根据ID获取字典数据项详细信息") + @ApiImplicitParam(name = "dictDataId", value = "字典数据ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDictDataEntity.class) + }) @PreAuthorize("@customSs.hasPermission('system:dict:query')") @GetMapping(value = "/{dictDataId}") public R getInfo(@PathVariable("dictDataId") Long dictDataId) { @@ -48,10 +64,15 @@ public class SysDictDataController { /** * 新增字典数据表 */ + @ApiOperation(value = "新增字典数据", notes = "创建新的字典数据项") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @PreAuthorize("@customSs.hasPermission('system:dict:create')") @Log(title = "字典数据表", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody SysDictDataEntity sysDictDataEntity) { + public R create(@ApiParam(value = "字典数据信息", required = true) @RequestBody SysDictDataEntity sysDictDataEntity) { boolean success = xlDictDataService.create(sysDictDataEntity); if (success) { return R.ok(); @@ -62,10 +83,16 @@ public class SysDictDataController { /** * 修改字典数据表 */ + @ApiOperation(value = "修改字典数据", notes = "根据ID修改字典数据项") + @ApiImplicitParam(name = "dictDataId", value = "字典数据ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PreAuthorize("@customSs.hasPermission('system:dict:edit')") @Log(title = "字典数据表", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{dictDataId}") - public R update(@PathVariable Long dictDataId, @RequestBody SysDictDataEntity sysDictDataEntity) { + public R update(@PathVariable Long dictDataId, @ApiParam(value = "字典数据信息", required = true) @RequestBody SysDictDataEntity sysDictDataEntity) { sysDictDataEntity.setDictDataId(dictDataId); boolean success = xlDictDataService.update(sysDictDataEntity); if (success) { @@ -77,6 +104,11 @@ public class SysDictDataController { /** * 删除字典数据表 */ + @ApiOperation(value = "删除字典数据", notes = "根据ID批量删除字典数据项") + @ApiImplicitParam(name = "dictDataIds", value = "字典数据ID数组", required = true, dataType = "Long[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('system:dict:remove')") @Log(title = "字典数据表", businessType = BusinessType.DELETE) @DeleteMapping("/{dictDataIds}") @@ -87,6 +119,11 @@ public class SysDictDataController { /** * 根据字典类型查询字典数据信息 */ + @ApiOperation(value = "根据类型查询字典数据", notes = "根据字典类型查询对应的字典数据项列表") + @ApiImplicitParam(name = "dictType", value = "字典类型", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysDictDataEntity.class, responseContainer = "List") + }) @GetMapping(value = "/type/{dictType}") public R getDictDataByType(@PathVariable String dictType) { List list = xlDictDataService.selectDictDataByType(dictType); diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysLoginLogController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysLoginLogController.java index e08e99c..1e70046 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysLoginLogController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysLoginLogController.java @@ -9,6 +9,13 @@ import com.starry.admin.utils.ExcelUtils; 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.ApiImplicitParams; +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.web.bind.annotation.*; @@ -21,6 +28,7 @@ import javax.servlet.http.HttpServletResponse; * * @author admin */ +@Api(tags = "登录日志管理", description = "系统访问日志相关接口") @RestController @RequestMapping("/system/loginlog") public class SysLoginLogController { @@ -30,9 +38,13 @@ public class SysLoginLogController { /** * 查询系统访问日志表列表 */ + @ApiOperation(value = "查询日志列表", notes = "分页查询系统访问日志列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysLoginLogEntity.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('system:loginlog:list')") @GetMapping("/list") - public R list(SysLoginLogVo vo) { + public R list(@ApiParam(value = "查询条件") SysLoginLogVo vo) { IPage list = xlLoginLogService.selectXlLoginLogList(vo); return R.ok(list); } @@ -40,10 +52,14 @@ public class SysLoginLogController { /** * 导出系统访问日志表列表 */ + @ApiOperation(value = "导出日志", notes = "导出系统访问日志表列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('system:loginlog:export')") @Log(title = "登录日志", businessType = BusinessType.EXPORT) @PostMapping("/export") - public void export(HttpServletResponse response, SysLoginLogVo vo) { + public void export(HttpServletResponse response, @ApiParam(value = "查询条件") SysLoginLogVo vo) { IPage list = xlLoginLogService.selectXlLoginLogList(vo); ExcelUtils.exportEasyExcel(response, SysLoginLogEntity.class, list.getRecords(), "系统访问日志表数据"); } @@ -51,6 +67,11 @@ public class SysLoginLogController { /** * 获取系统访问日志表详细信息 */ + @ApiOperation(value = "获取日志详情", notes = "根据ID获取系统访问日志详细信息") + @ApiImplicitParam(name = "loginId", value = "日志ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysLoginLogEntity.class) + }) @PreAuthorize("@customSs.hasPermission('system:log:query')") @GetMapping(value = "/{loginId}") public R getInfo(@PathVariable("loginId") Long loginId) { @@ -60,6 +81,11 @@ public class SysLoginLogController { /** * 删除系统访问日志表 */ + @ApiOperation(value = "删除日志", notes = "根据ID批量删除系统访问日志") + @ApiImplicitParam(name = "loginIds", value = "日志ID数组", required = true, dataType = "Long[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('system:loginlog:remove')") @Log(title = "登录日志", businessType = BusinessType.DELETE) @DeleteMapping("/{loginIds}") @@ -67,6 +93,10 @@ public class SysLoginLogController { return R.ok(xlLoginLogService.deleteXlLoginLogByLoginIds(loginIds)); } + @ApiOperation(value = "清空日志", notes = "清空所有系统访问日志") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('monitor:logininfor:clean')") @Log(title = "登录日志", businessType = BusinessType.CLEAN) @DeleteMapping("/clean") diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysMenuController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysMenuController.java index 654d9da..92105bb 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysMenuController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysMenuController.java @@ -10,7 +10,13 @@ import com.starry.admin.modules.system.vo.SimpleMenu; import com.starry.admin.utils.SecurityUtils; import com.starry.common.constant.UserConstants; import com.starry.common.result.R; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiImplicitParam; +import io.swagger.annotations.ApiImplicitParams; 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.web.bind.annotation.*; @@ -26,6 +32,7 @@ import java.util.stream.Collectors; * @author admin * @since 2022-07-03 */ +@Api(tags = "菜单管理", description = "系统菜单管理相关接口") @RestController @RequestMapping("/ucenter/menu") public class SysMenuController { @@ -34,29 +41,43 @@ public class SysMenuController { private SysMenuService menuService; - @ApiOperation("获取菜单列表") + @ApiOperation(value = "获取菜单列表", notes = "获取系统所有菜单列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysMenuEntity.class, responseContainer = "List") + }) @PreAuthorize("@customSs.hasPermission('system:menu:list')") @GetMapping("/list") - public R list(SysMenuEntity menu) { + public R list(@ApiParam(value = "菜单查询条件") SysMenuEntity menu) { // 获取登录人的userId; String userId = SecurityUtils.getUserId(); List menus = menuService.selectMenuList(menu, userId); return R.ok(menus); } - @ApiOperation("分页获取菜单列表") + @ApiOperation(value = "分页获取菜单列表", notes = "分页查询系统菜单列表") + @ApiImplicitParams({ + @ApiImplicitParam(name = "pageSize", value = "每页记录数", defaultValue = "5", dataType = "Integer", paramType = "query"), + @ApiImplicitParam(name = "pageNum", value = "页码", defaultValue = "1", dataType = "Integer", paramType = "query") + }) + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysMenuEntity.class, responseContainer = "Page") + }) @GetMapping("/list-page") - public R listPage(@RequestParam(value = "menu", required = false) SysMenuEntity menu, + public R listPage(@ApiParam(value = "菜单查询条件") @RequestParam(value = "menu", required = false) SysMenuEntity menu, @RequestParam(value = "pageSize", defaultValue = "5") Integer pageSize, @RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum) { Page pageMenu = menuService.listPage(menu, SecurityUtils.getUserId(), pageSize, pageNum); return R.ok(pageMenu); } - @ApiOperation("添加菜单") + @ApiOperation(value = "添加菜单", notes = "创建新的系统菜单") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败，菜单名称已存在或地址格式错误") + }) @PreAuthorize("@customSs.hasPermission('system:menu:create')") @PostMapping("/create") - public R create(@RequestBody SysMenuEntity menu) { + public R create(@ApiParam(value = "菜单信息", required = true) @RequestBody SysMenuEntity menu) { if (UserConstants.NOT_UNIQUE.equals(menuService.checkMenuNameUnique(menu))) { return R.error("新增菜单'" + menu.getMenuName() + "'失败，菜单名称已存在"); } else if (UserConstants.YES_FRAME.equals(menu.getIsFrame()) && !StrUtil.startWithAny(menu.getPath(), "http://", "https://")) { @@ -69,10 +90,15 @@ public class SysMenuController { return R.error("添加失败"); } - @ApiOperation("修改菜单") + @ApiOperation(value = "修改菜单", notes = "根据ID修改菜单信息") + @ApiImplicitParam(name = "id", value = "菜单ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败，菜单名称已存在或地址格式错误") + }) @PreAuthorize("@customSs.hasPermission('system:menu:edit')") @PostMapping("/update/{id}") - public R update(@PathVariable Long id, @RequestBody SysMenuEntity menu) { + public R update(@PathVariable Long id, @ApiParam(value = "菜单信息", required = true) @RequestBody SysMenuEntity menu) { menu.setMenuId(id); if (UserConstants.NOT_UNIQUE.equals(menuService.checkMenuNameUnique(menu))) { return R.error("修改菜单'" + menu.getMenuName() + "'失败，菜单名称已存在"); @@ -89,7 +115,12 @@ public class SysMenuController { } - @ApiOperation("删除菜单") + @ApiOperation(value = "删除菜单", notes = "根据ID删除菜单") + @ApiImplicitParam(name = "id", value = "菜单ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "删除失败，存在子菜单") + }) @PreAuthorize("@customSs.hasPermission('system:menu:delete')") @PostMapping(value = "/delete/{id}") public R delete(@PathVariable("id") Long menuId) { @@ -103,22 +134,33 @@ public class SysMenuController { return R.error("删除失败"); } - @ApiOperation("获取菜单下拉树列表") + @ApiOperation(value = "获取菜单下拉树列表", notes = "获取菜单的树形结构") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = TreeSelect.class, responseContainer = "List") + }) @GetMapping("/treeselect") - public R treeselect(SysMenuEntity menu) { + public R treeselect(@ApiParam(value = "菜单查询条件") SysMenuEntity menu) { List menus = menuService.selectMenuList(menu, SecurityUtils.getUserId()); List tree = menuService.buildMenuTreeSelect(menus); return R.ok(tree); } + @ApiOperation(value = "获取菜单详情", notes = "根据菜单ID获取菜单详细信息") + @ApiImplicitParam(name = "menuId", value = "菜单ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysMenuEntity.class) + }) @PreAuthorize("@customSs.hasPermission('system:menu:query')") - @ApiOperation("根据菜单编号获取详细信息") @GetMapping(value = "/{menuId}") public R getInfo(@PathVariable Long menuId) { return R.ok(menuService.selectMenuById(menuId)); } - @ApiOperation("获取对应角色菜单列表树") + @ApiOperation(value = "获取角色菜单树", notes = "获取指定角色的菜单树形结构") + @ApiImplicitParam(name = "roleId", value = "角色ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class) + }) @GetMapping(value = "/roleMenuTreeselect/{roleId}") public R roleMenuTreeselect(@PathVariable("roleId") Long roleId) { List menus = menuService.selectMenuList(SecurityUtils.getUserId()); @@ -128,9 +170,11 @@ public class SysMenuController { return R.ok(resultMap); } + @ApiOperation(value = "获取菜单精简信息列表", notes = "只包含被开启的菜单，用于【角色分配菜单】功能的选项。在多租户的场景下，会只返回租户所在套餐有的菜单") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SimpleMenu.class, responseContainer = "List") + }) @GetMapping("/list-all-simple") - @ApiOperation(value = "获取菜单精简信息列表", notes = "只包含被开启的菜单，用于【角色分配菜单】功能的选项。" + - "在多租户的场景下，会只返回租户所在套餐有的菜单") public R getSimpleMenus() { // 获得菜单列表，只要开启状态的 List menus = menuService.selectSimpleMenuList(); diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysOperationLogController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysOperationLogController.java index 6587666..a90133a 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysOperationLogController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysOperationLogController.java @@ -8,6 +8,13 @@ import com.starry.admin.utils.ExcelUtils; 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.ApiImplicitParams; +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.web.bind.annotation.*; @@ -20,6 +27,7 @@ import javax.servlet.http.HttpServletResponse; * * @author admin */ +@Api(tags = "操作日志管理", description = "系统操作日志相关接口") @RestController @RequestMapping("/system/operlog") public class SysOperationLogController { @@ -30,15 +38,24 @@ public class SysOperationLogController { /** * 查询操作日志表列表 */ + @ApiOperation(value = "查询操作日志列表", notes = "分页查询系统操作日志列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysOperationLogEntity.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('system:operlog:list')") @GetMapping("/list") - public R list(SysOperationLogVo sysOperationLogEntity) { + public R list(@ApiParam(value = "查询条件") SysOperationLogVo sysOperationLogEntity) { return R.ok(xlOperLogService.selectXlOperLogList(sysOperationLogEntity)); } /** * 获取操作日志表详细信息 */ + @ApiOperation(value = "获取操作日志详情", notes = "根据ID获取操作日志详细信息") + @ApiImplicitParam(name = "operId", value = "日志ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysOperationLogEntity.class) + }) @PreAuthorize("@customSs.hasPermission('system:operlog:query')") @GetMapping(value = "/{operId}") public R getInfo(@PathVariable("operId") Long operId) { @@ -48,10 +65,15 @@ public class SysOperationLogController { /** * 新增操作日志表 */ + @ApiOperation(value = "新增操作日志", notes = "手动创建系统操作日志记录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @PreAuthorize("@customSs.hasPermission('system:operlog:create')") @Log(title = "操作日志表", businessType = BusinessType.INSERT) @PostMapping - public R create(@RequestBody SysOperationLogEntity sysOperationLogEntity) { + public R create(@ApiParam(value = "操作日志信息", required = true) @RequestBody SysOperationLogEntity sysOperationLogEntity) { boolean success = xlOperLogService.create(sysOperationLogEntity); if (success) { return R.ok(); @@ -62,10 +84,16 @@ public class SysOperationLogController { /** * 修改操作日志表 */ + @ApiOperation(value = "修改操作日志", notes = "根据ID修改操作日志信息") + @ApiImplicitParam(name = "operId", value = "日志ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PreAuthorize("@customSs.hasPermission('system:operlog:edit')") @Log(title = "操作日志表", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{operId}") - public R update(@PathVariable Long operId, @RequestBody SysOperationLogEntity sysOperationLogEntity) { + public R update(@PathVariable Long operId, @ApiParam(value = "操作日志信息", required = true) @RequestBody SysOperationLogEntity sysOperationLogEntity) { sysOperationLogEntity.setOperId(operId); boolean success = xlOperLogService.updateXlOperLog(sysOperationLogEntity); if (success) { @@ -77,6 +105,11 @@ public class SysOperationLogController { /** * 删除操作日志表 */ + @ApiOperation(value = "删除操作日志", notes = "根据ID批量删除操作日志") + @ApiImplicitParam(name = "operIds", value = "日志ID数组", required = true, dataType = "Long[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('system:operlog:remove')") @Log(title = "操作日志表", businessType = BusinessType.DELETE) @DeleteMapping("/{operIds}") @@ -87,10 +120,14 @@ public class SysOperationLogController { /** * 导出操作日志表 */ + @ApiOperation(value = "导出操作日志", notes = "导出系统操作日志表数据") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('system:operlog:export')") @Log(title = "操作日志", businessType = BusinessType.EXPORT) @PostMapping("/export") - public void export(HttpServletResponse response, SysOperationLogVo sysOperationLogEntity) { + public void export(HttpServletResponse response, @ApiParam(value = "查询条件") SysOperationLogVo sysOperationLogEntity) { ExcelUtils.exportEasyExcel(response, SysOperationLogEntity.class, xlOperLogService.selectXlOperLogList(sysOperationLogEntity).getRecords(), "系统操作日志表数据"); } } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysRoleController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysRoleController.java index 60aa544..a624d34 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysRoleController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysRoleController.java @@ -17,7 +17,12 @@ import com.starry.common.constant.UserConstants; 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.ApiImplicitParams; import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.beans.BeanUtils; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.validation.annotation.Validated; @@ -36,7 +41,7 @@ import java.util.Map; * @author admin * @since 2022-07-01 */ -@Api(tags = "角色管理") +@Api(tags = "角色管理", description = "系统角色管理相关接口") @RestController @RequestMapping("/ucenter/role") public class SysRoleController { @@ -48,10 +53,14 @@ public class SysRoleController { @Resource private SysUserService userService; - @ApiOperation("添加角色") + @ApiOperation(value = "添加角色", notes = "创建新的系统角色") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "操作失败，角色名称或权限已存在") + }) @PreAuthorize("@customSs.hasPermission('system:role:create')") @PostMapping("/create") - public R create(@Validated @RequestBody SysRoleAddVo roleAddVo) { + public R create(@ApiParam(value = "角色信息", required = true) @Validated @RequestBody SysRoleAddVo roleAddVo) { SysRoleEntity role = new SysRoleEntity(); BeanUtils.copyProperties(roleAddVo, role); if (UserConstants.NOT_UNIQUE.equals(roleService.checkRoleNameUnique(role))) { @@ -66,10 +75,15 @@ public class SysRoleController { return R.error("添加失败"); } - @ApiOperation("修改角色") + @ApiOperation(value = "修改角色", notes = "根据ID修改角色信息") + @ApiImplicitParam(name = "id", value = "角色ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败，角色名称或权限已存在") + }) @PreAuthorize("@customSs.hasPermission('system:role:edit')") @PostMapping("/update/{id}") - public R update(@PathVariable Long id, @RequestBody SysRoleEntity role) { + public R update(@PathVariable Long id, @ApiParam(value = "角色信息", required = true) @RequestBody SysRoleEntity role) { role.setRoleId(id); roleService.checkRoleAllowed(role); roleService.checkRoleDataScope(role.getRoleId()); @@ -85,7 +99,12 @@ public class SysRoleController { return R.error("修改失败"); } - @ApiOperation("批量删除角色") + @ApiOperation(value = "批量删除角色", notes = "根据ID批量删除角色") + @ApiImplicitParam(name = "roleIds", value = "角色ID数组", required = true, dataType = "Long[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "删除失败") + }) @PreAuthorize("@customSs.hasPermission('system:role:remove')") @DeleteMapping("/{roleIds}") public R delete(@PathVariable Long[] roleIds) { @@ -96,21 +115,40 @@ public class SysRoleController { return R.error("删除失败"); } - @ApiOperation("获取所有角色") + @ApiOperation(value = "获取所有角色", notes = "获取系统中所有角色列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysRoleEntity.class, responseContainer = "List") + }) @GetMapping("/list-all") public R listAll() { List list = roleService.list(); return R.ok(list); } - @ApiOperation("根据角色名称分页获取角色列表") + @ApiOperation(value = "分页获取角色列表", notes = "根据角色名称分页获取角色列表") + @ApiImplicitParams({ + @ApiImplicitParam(name = "keyword", value = "搜索关键词", dataType = "String", paramType = "query"), + @ApiImplicitParam(name = "pageSize", value = "每页记录数", defaultValue = "5", dataType = "Integer", paramType = "query"), + @ApiImplicitParam(name = "pageNum", value = "页码", defaultValue = "1", dataType = "Integer", paramType = "query") + }) + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysRoleEntity.class, responseContainer = "Page") + }) @GetMapping("/list-page") public R listPage(@RequestParam(value = "keyword", required = false) String keyword, @RequestParam(value = "pageSize", defaultValue = "5") Integer pageSize, @RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum) { Page rolePage = roleService.list(keyword, pageSize, pageNum); return R.ok(rolePage); } - @ApiOperation("修改角色状态") + @ApiOperation(value = "修改角色状态", notes = "启用或禁用角色") + @ApiImplicitParams({ + @ApiImplicitParam(name = "id", value = "角色ID", required = true, dataType = "Long", paramType = "path"), + @ApiImplicitParam(name = "status", value = "状态(0-正常,1-停用)", required = true, dataType = "Integer", paramType = "query") + }) + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PreAuthorize("@customSs.hasPermission('system:role:edit')") @PostMapping("/update-status/{id}") public R updateStatus(@PathVariable Long id, @RequestParam(value = "status") Integer status) { @@ -124,10 +162,14 @@ public class SysRoleController { return R.error("修改失败"); } - @ApiOperation("分配菜单权限") + @ApiOperation(value = "分配菜单权限", notes = "为角色分配菜单权限") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "分配失败") + }) @PreAuthorize("@customSs.hasPermission('system:role:auth')") @PostMapping("/auth-role-menu") - public R authRoleMenu(@RequestBody SysRoleEntity role) { + public R authRoleMenu(@ApiParam(value = "角色信息", required = true) @RequestBody SysRoleEntity role) { boolean success = roleService.authRoleMenu(role); if (success) { return R.ok(); @@ -138,6 +180,11 @@ public class SysRoleController { /** * 根据角色编号获取详细信息 */ + @ApiOperation(value = "获取角色详情", notes = "根据角色ID获取角色详细信息") + @ApiImplicitParam(name = "roleId", value = "角色ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysRoleEntity.class) + }) @GetMapping(value = "/{roleId}") public R getInfo(@PathVariable Long roleId) { roleService.checkRoleDataScope(roleId); @@ -147,7 +194,11 @@ public class SysRoleController { /** * 获取对应角色部门树列表 */ - @ApiOperation("获取对应角色部门树列表") + @ApiOperation(value = "获取角色部门树列表", notes = "获取角色关联的部门树结构") + @ApiImplicitParam(name = "roleId", value = "角色ID", required = true, dataType = "Long", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class) + }) @GetMapping(value = "/deptTree/{roleId}") public R deptTree(@PathVariable("roleId") Long roleId) { Map resultMap = new HashMap<>(8); @@ -159,10 +210,13 @@ public class SysRoleController { /** * 修改保存数据权限 */ - @ApiOperation("修改保存数据权限") + @ApiOperation(value = "保存数据权限", notes = "修改角色的数据权限范围") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @Log(title = "角色管理-保存数据权限", businessType = BusinessType.UPDATE) @PostMapping("/dataScope") - public R dataScope(@RequestBody SysRoleEntity role) { + public R dataScope(@ApiParam(value = "角色信息", required = true) @RequestBody SysRoleEntity role) { roleService.checkRoleAllowed(role); roleService.checkRoleDataScope(role.getRoleId()); return R.ok(roleService.authDataScope(role)); @@ -171,7 +225,10 @@ public class SysRoleController { /** * 查询已分配用户角色列表 */ - @ApiOperation("查询已分配用户角色列表") + @ApiOperation(value = "查询已分配用户角色列表", notes = "获取已经分配给指定角色的用户列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = RoleUserResultVo.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('system:role:list')") @GetMapping("/authUser/allocatedList") public R allocatedList(SysUserQueryVo user) { @@ -182,7 +239,10 @@ public class SysRoleController { /** * 查询未分配用户角色列表 */ - @ApiOperation("查询未分配用户角色列表") + @ApiOperation(value = "查询未分配用户角色列表", notes = "获取尚未分配给指定角色的用户列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = RoleUserResultVo.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('system:role:list')") @GetMapping("/authUser/unallocatedList") public R unallocatedList(SysUserQueryVo user) { @@ -192,18 +252,28 @@ public class SysRoleController { /** * 取消授权用户 */ - @ApiOperation("取消授权用户") + @ApiOperation(value = "取消授权用户", notes = "取消指定用户的角色授权") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('system:role:edit')") @Log(title = "角色管理", businessType = BusinessType.GRANT) @PutMapping("/authUser/cancel") - public R cancelAuthUser(@RequestBody SysUserRoleEntity userRole) { + public R cancelAuthUser(@ApiParam(value = "用户角色关系", required = true) @RequestBody SysUserRoleEntity userRole) { return R.ok(roleService.deleteAuthUser(userRole)); } /** * 批量取消授权用户 */ - @ApiOperation("批量取消授权用户") + @ApiOperation(value = "批量取消授权用户", notes = "批量取消多个用户的角色授权") + @ApiImplicitParams({ + @ApiImplicitParam(name = "roleId", value = "角色ID", required = true, dataType = "Long", paramType = "query"), + @ApiImplicitParam(name = "userIds", value = "用户ID数组", required = true, dataType = "String[]", paramType = "query") + }) + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('system:role:edit')") @Log(title = "角色管理", businessType = BusinessType.GRANT) @PutMapping("/authUser/cancelAll") @@ -214,7 +284,14 @@ public class SysRoleController { /** * 批量选择用户授权 */ - @ApiOperation("批量选择用户授权") + @ApiOperation(value = "批量选择用户授权", notes = "为角色批量添加用户授权") + @ApiImplicitParams({ + @ApiImplicitParam(name = "roleId", value = "角色ID", required = true, dataType = "Long", paramType = "query"), + @ApiImplicitParam(name = "userIds", value = "用户ID数组", required = true, dataType = "String[]", paramType = "query") + }) + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('system:role:edit')") @Log(title = "角色管理", businessType = BusinessType.GRANT) @PutMapping("/authUser/selectAll") diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysSmsController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysSmsController.java index 7d2e04b..664c902 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysSmsController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysSmsController.java @@ -4,6 +4,11 @@ import com.starry.admin.modules.system.module.entity.SysTenantEntity; import com.starry.admin.modules.system.service.ISysTenantService; import com.starry.admin.utils.SmsUtils; 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.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -18,6 +23,7 @@ import javax.annotation.Resource; * @author admin * @since 2024/5/20 下午11:19 **/ +@Api(tags = "短信管理", description = "系统短信发送相关接口") @Slf4j @RestController @RequestMapping("/system/sms") @@ -27,12 +33,21 @@ public class SysSmsController { @Resource private ISysTenantService tenantService; + @ApiOperation(value = "发送短信", notes = "向指定手机号发送短信验证码") + @ApiImplicitParam(name = "phone", value = "手机号码", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("/send") public R sendSms(@RequestParam("phone") String phone) { smsUtils.sendSmsApi(phone); return R.ok(); } + @ApiOperation(value = "测试接口", notes = "测试租户角色初始化") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @GetMapping("/test") public R test() { SysTenantEntity sysTenantEntity = tenantService.selectSysTenantByTenantId("y5PNjqco"); diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantController.java index 8910eee..a5fbba8 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantController.java @@ -13,6 +13,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.beans.BeanUtils; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.validation.annotation.Validated; @@ -28,6 +34,7 @@ import java.util.List; * * @author admin */ +@Api(tags = "租户管理", description = "系统租户相关接口") @RestController @RequestMapping("/platform/tenant") public class SysTenantController { @@ -44,10 +51,15 @@ public class SysTenantController { /** * 新增租户表 */ + @ApiOperation(value = "新增租户", notes = "创建新的系统租户") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) //@PreAuthorize("@customSs.hasPermission('platform:tenant:create')") @Log(title = "租户表", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@Validated @RequestBody SysTenantAddVo vo) { + public R create(@ApiParam(value = "租户信息", required = true) @Validated @RequestBody SysTenantAddVo vo) { SysTenantEntity entity = ConvertUtil.entityToVo(vo, SysTenantEntity.class); return sysTenantService.addTenant(entity); } @@ -56,9 +68,13 @@ public class SysTenantController { /** * 查询租户表列表 */ + @ApiOperation(value = "分页查询租户列表", notes = "根据条件分页查询租户列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysTenantReturnVo.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('platform:tenant:list')") @PostMapping("/listByPage") - public R listByPage(@RequestBody SysTenantQueryVo vo) { + public R listByPage(@ApiParam(value = "查询条件", required = true) @RequestBody SysTenantQueryVo vo) { IPage page = sysTenantService.selectSysTenantList(vo); IPage voPage = page.convert(u -> { SysTenantReturnVo returnVo = new SysTenantReturnVo(); @@ -84,6 +100,11 @@ public class SysTenantController { /** * 获取租户表详细信息 */ + @ApiOperation(value = "获取租户详情", notes = "根据租户ID获取租户详细信息") + @ApiImplicitParam(name = "tenantId", value = "租户ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysTenantEntity.class) + }) @PreAuthorize("@customSs.hasPermission('platform:tenant:query')") @GetMapping(value = "/{tenantId}") public R getInfo(@PathVariable("tenantId") String tenantId) { @@ -94,16 +115,27 @@ public class SysTenantController { /** * 修改租户表 */ + @ApiOperation(value = "修改租户", notes = "根据租户ID修改租户信息") + @ApiImplicitParam(name = "tenantId", value = "租户ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PreAuthorize("@customSs.hasPermission('platform:tenant:edit')") @Log(title = "租户表", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{tenantId}") - public R update(@PathVariable String tenantId, @RequestBody SysTenantEntity sysTenantEntity) { + public R update(@PathVariable String tenantId, @ApiParam(value = "租户信息", required = true) @RequestBody SysTenantEntity sysTenantEntity) { return sysTenantService.updateTenant(sysTenantEntity); } /** * 删除租户表 */ + @ApiOperation(value = "删除租户", notes = "根据租户ID批量删除租户") + @ApiImplicitParam(name = "tenantIds", value = "租户ID数组", required = true, dataType = "String[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('platform:tenant:remove')") @Log(title = "租户表", businessType = BusinessType.DELETE) @DeleteMapping("/{tenantIds}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantPackageController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantPackageController.java index 57d99e4..0b74099 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantPackageController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantPackageController.java @@ -9,6 +9,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.web.bind.annotation.*; @@ -22,6 +28,7 @@ import java.util.List; * * @author admin */ +@Api(tags = "租户套餐管理", description = "系统租户套餐相关接口") @RestController @RequestMapping("/platform/package") public class SysTenantPackageController { @@ -31,25 +38,38 @@ public class SysTenantPackageController { /** * 查询租户套餐表列表 */ + @ApiOperation(value = "查询租户套餐列表", notes = "分页查询租户套餐列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysTenantPackageEntity.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('platform:package:list')") @GetMapping("/list") - public R list(SysTenantPackageVo sysTenantPackageEntity) { + public R list(@ApiParam(value = "查询条件") SysTenantPackageVo sysTenantPackageEntity) { return R.ok(SysTenantPackageService.selectSysTenantPackageList(sysTenantPackageEntity)); } /** * 导出租户套餐表列表 */ + @ApiOperation(value = "导出租户套餐", notes = "导出租户套餐表数据到Excel") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('platform:package:export')") @Log(title = "租户套餐表", businessType = BusinessType.EXPORT) @PostMapping("/export") - public void export(HttpServletResponse response, SysTenantPackageVo sysTenantPackageEntity) { + public void export(HttpServletResponse response, @ApiParam(value = "查询条件") SysTenantPackageVo sysTenantPackageEntity) { ExcelUtils.exportEasyExcel(response, SysTenantPackageEntity.class, SysTenantPackageService.selectSysTenantPackageList(sysTenantPackageEntity).getRecords(), "租户套餐表数据"); } /** * 获取租户套餐表详细信息 */ + @ApiOperation(value = "获取租户套餐详情", notes = "根据ID获取租户套餐详细信息") + @ApiImplicitParam(name = "packageId", value = "套餐ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysTenantPackageEntity.class) + }) @PreAuthorize("@customSs.hasPermission('platform:package:query')") @GetMapping(value = "/{packageId}") public R getInfo(@PathVariable("packageId") String packageId) { @@ -59,10 +79,15 @@ public class SysTenantPackageController { /** * 新增租户套餐表 */ + @ApiOperation(value = "新增租户套餐", notes = "创建新的租户套餐") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) @PreAuthorize("@customSs.hasPermission('platform:package:create')") @Log(title = "租户套餐表", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@RequestBody SysTenantPackageEntity vo) { + public R create(@ApiParam(value = "套餐信息", required = true) @RequestBody SysTenantPackageEntity vo) { SysTenantPackageEntity entity = ConvertUtil.entityToVo(vo, SysTenantPackageEntity.class); boolean success = SysTenantPackageService.create(entity); if (success) { @@ -74,10 +99,16 @@ public class SysTenantPackageController { /** * 修改租户套餐表 */ + @ApiOperation(value = "修改租户套餐", notes = "根据ID修改租户套餐信息") + @ApiImplicitParam(name = "packageId", value = "套餐ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PreAuthorize("@customSs.hasPermission('platform:package:edit')") @Log(title = "租户套餐表", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{packageId}") - public R update(@PathVariable String packageId, @RequestBody SysTenantPackageEntity sysTenantPackageEntity) { + public R update(@PathVariable String packageId, @ApiParam(value = "套餐信息", required = true) @RequestBody SysTenantPackageEntity sysTenantPackageEntity) { sysTenantPackageEntity.setPackageId(packageId); boolean success = SysTenantPackageService.update(sysTenantPackageEntity); @@ -90,6 +121,11 @@ public class SysTenantPackageController { /** * 删除租户套餐表 */ + @ApiOperation(value = "删除租户套餐", notes = "根据ID批量删除租户套餐") + @ApiImplicitParam(name = "packageIds", value = "套餐ID数组", required = true, dataType = "String[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) @PreAuthorize("@customSs.hasPermission('platform:package:remove')") @Log(title = "租户套餐表", businessType = BusinessType.DELETE) @DeleteMapping("/{packageIds}") @@ -100,6 +136,10 @@ public class SysTenantPackageController { /** * 查询租户套餐精简列表 */ + @ApiOperation(value = "查询套餐精简列表", notes = "获取租户套餐的精简信息列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SimplePackage.class, responseContainer = "List") + }) @GetMapping("/get-simple-list") public R getSimpleList() { List list = SysTenantPackageService.getSimpleList(); diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantRechargeInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantRechargeInfoController.java index ec8af8c..b8c4e1d 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantRechargeInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysTenantRechargeInfoController.java @@ -7,6 +7,12 @@ import com.starry.admin.modules.system.service.ISysTenantRechargeInfoService; 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.beans.BeanUtils; import org.springframework.security.access.prepost.PreAuthorize; import org.springframework.validation.annotation.Validated; @@ -20,6 +26,7 @@ import javax.annotation.Resource; * @author admin * @since 2024-09-05 */ +@Api(tags = "租户充值管理", description = "租户充值记录相关接口") @RestController @RequestMapping("/platform/recharge") public class SysTenantRechargeInfoController { @@ -29,15 +36,24 @@ public class SysTenantRechargeInfoController { /** * 查询租户充值信息列表 */ + @ApiOperation(value = "查询充值记录", notes = "分页查询租户充值记录列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysTenantRechargeInfoEntity.class, responseContainer = "Page") + }) // @PreAuthorize("@customSs.hasPermission('play:info:list')") @PostMapping("/listByPage") - public R list(@Validated @RequestBody SysTenantRechargeInfoQueryVo vo) { + public R list(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody SysTenantRechargeInfoQueryVo vo) { return R.ok(sysTenantRechargeInfoService.selectByPage(vo)); } /** * 获取租户充值信息详细信息 */ + @ApiOperation(value = "获取充值详情", notes = "根据ID获取租户充值记录详细信息") + @ApiImplicitParam(name = "id", value = "充值记录ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysTenantRechargeInfoEntity.class) + }) // @PreAuthorize("@customSs.hasPermission('play:info:query')") @GetMapping(value = "/{id}") public R getInfo(@PathVariable("id") String id) { @@ -47,10 +63,15 @@ public class SysTenantRechargeInfoController { /** * 新增租户充值信息 */ + @ApiOperation(value = "新增充值记录", notes = "创建租户充值记录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "添加失败") + }) // @PreAuthorize("@customSs.hasPermission('play:info:create')") @Log(title = "租户充值信息", businessType = BusinessType.INSERT) @PostMapping("/create") - public R create(@Validated @RequestBody SysTenantRechargeInfoAddVo addVo) { + public R create(@ApiParam(value = "充值信息", required = true) @Validated @RequestBody SysTenantRechargeInfoAddVo addVo) { SysTenantRechargeInfoEntity entity = new SysTenantRechargeInfoEntity(); BeanUtils.copyProperties(addVo, entity); boolean success = sysTenantRechargeInfoService.create(entity); @@ -63,10 +84,16 @@ public class SysTenantRechargeInfoController { /** * 修改租户充值信息 */ + @ApiOperation(value = "修改充值记录", notes = "根据ID修改租户充值记录") + @ApiImplicitParam(name = "id", value = "充值记录ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PreAuthorize("@customSs.hasPermission('play:info:edit')") @Log(title = "租户充值信息", businessType = BusinessType.UPDATE) @PostMapping(value = "/update/{id}") - public R update(@PathVariable String id, @RequestBody SysTenantRechargeInfoEntity sysTenantRechargeInfo) { + public R update(@PathVariable String id, @ApiParam(value = "充值信息", required = true) @RequestBody SysTenantRechargeInfoEntity sysTenantRechargeInfo) { sysTenantRechargeInfo.setId(id); boolean success = sysTenantRechargeInfoService.update(sysTenantRechargeInfo); if (success) { @@ -78,6 +105,11 @@ public class SysTenantRechargeInfoController { /** * 删除租户充值信息 */ + @ApiOperation(value = "删除充值记录", notes = "根据ID批量删除租户充值记录") + @ApiImplicitParam(name = "ids", value = "充值记录ID数组", required = true, dataType = "String[]", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Boolean.class) + }) // @PreAuthorize("@customSs.hasPermission('play:info:remove')") @Log(title = "租户充值信息", businessType = BusinessType.DELETE) @DeleteMapping("/{ids}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysUserController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysUserController.java index ffebb79..313e31d 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysUserController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/SysUserController.java @@ -17,7 +17,12 @@ import com.starry.common.constant.UserConstants; 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.ApiImplicitParams; import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiParam; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.*; import org.springframework.web.multipart.MultipartFile; @@ -37,7 +42,7 @@ import java.util.stream.Collectors; * @author admin * @since 2021-09-03 */ -@Api(tags = "用户管理") +@Api(tags = "用户管理", description = "系统用户管理相关接口") @RestController @RequestMapping("/ucenter/user") public class SysUserController { @@ -52,9 +57,13 @@ public class SysUserController { @Resource private IOssFileService ossFileService; - @ApiOperation(value = "注册用户") + @ApiOperation(value = "注册用户", notes = "新用户注册接口") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysUserEntity.class), + @ApiResponse(code = 500, message = "操作失败") + }) @PostMapping(value = "register") - public R register(@RequestBody SysUserEntity user) { + public R register(@ApiParam(value = "用户信息", required = true) @RequestBody SysUserEntity user) { SysUserEntity sysUserEntity = userService.register(user); if (sysUserEntity == null) { return R.error("注册失败,用户名已存在"); @@ -62,14 +71,20 @@ public class SysUserController { return R.ok(sysUserEntity); } - @ApiOperation(value = "分页用户列表") + @ApiOperation(value = "分页用户列表", notes = "分页查询用户列表信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysUserEntity.class, responseContainer = "Page") + }) @GetMapping(value = "/list-page") public R listPage(UserQueryVo queryVo) { IPage page = userService.listMemberPage(queryVo); return R.ok(page); } - @ApiOperation(value = "分页用户列表") + @ApiOperation(value = "分页用户列表(V1)", notes = "分页查询用户列表信息，返回格式化后的结果") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = SysUserEntityListVo.class, responseContainer = "Page") + }) @GetMapping(value = "/list-page/v1") public R listPageV1(UserQueryVo queryVo) { IPage page = userService.listMemberPage(queryVo); @@ -81,9 +96,13 @@ public class SysUserController { return R.ok(result); } - @ApiOperation(value = "添加用户") + @ApiOperation(value = "添加用户", notes = "创建新的系统用户") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "操作失败，登录账号已存在") + }) @PostMapping(value = "add") - public R add(@RequestBody SysUserEntity user) { + public R add(@ApiParam(value = "用户信息", required = true) @RequestBody SysUserEntity user) { if (UserConstants.NOT_UNIQUE.equals(userService.checkUserNameUnique(user.getUserCode()))) { return R.error("新增用户'" + user.getUserCode() + "'失败，登录账号已存在"); } @@ -94,16 +113,24 @@ public class SysUserController { return R.error("添加失败"); } - @ApiOperation(value = "添加用户") + @ApiOperation(value = "添加用户(V1)", notes = "创建新的系统用户，使用参数对象") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PostMapping(value = "add/v1") - public R addV1(@Valid @RequestBody UserAddParam param) { + public R addV1(@ApiParam(value = "用户添加参数", required = true) @Valid @RequestBody UserAddParam param) { boolean success = userService.addV1(param); return R.ok(); } - @ApiOperation(value = "修改用户") + @ApiOperation(value = "修改用户", notes = "根据ID修改用户信息") + @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "修改失败") + }) @PostMapping(value = "/update/{id}") - public R update(@PathVariable("id") String id, @RequestBody SysUserEntity user) { + public R update(@PathVariable("id") String id, @ApiParam(value = "用户信息", required = true) @RequestBody SysUserEntity user) { user.setUserId(id); boolean flag = userService.update(user); if (flag) { @@ -112,21 +139,32 @@ public class SysUserController { return R.error("修改失败"); } - @ApiOperation(value = "修改用户密码") + @ApiOperation(value = "修改用户密码", notes = "修改当前用户的密码") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PostMapping(value = "/update/password") - public R updatePassword(@Valid @RequestBody UpdateUserPasswordParam param) { + public R updatePassword(@ApiParam(value = "密码修改参数", required = true) @Valid @RequestBody UpdateUserPasswordParam param) { userService.updatePassword(param); return R.ok(); } - @ApiOperation(value = "修改用户手机号") + @ApiOperation(value = "修改用户手机号", notes = "修改当前用户的手机号") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PostMapping(value = "/update/mobile") - public R updateMobile(@Valid @RequestBody UpdateUserMobileParam param) { + public R updateMobile(@ApiParam(value = "手机号修改参数", required = true) @Valid @RequestBody UpdateUserMobileParam param) { userService.updateMobile(param); return R.ok(); } - @ApiOperation(value = "删除用户") + @ApiOperation(value = "删除用户", notes = "根据ID删除用户") + @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "操作失败") + }) @PostMapping(value = "/delete/{id}") public R delete(@PathVariable("id") String id) { boolean flag = userService.delete(Collections.singletonList(id)); @@ -136,13 +174,20 @@ public class SysUserController { return R.error(); } - @ApiOperation(value = "登出功能") + @ApiOperation(value = "登出功能", notes = "用户登出系统") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PostMapping(value = "logout") public R logout() { return R.ok(); } - @ApiOperation(value = "根据用户id获取详细信息") + @ApiOperation(value = "获取用户详情", notes = "根据用户ID获取用户详细信息，不传ID则获取当前用户") + @ApiImplicitParam(name = "userId", value = "用户ID", required = false, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class) + }) @GetMapping(value = {"/", "/{userId}"}) public R getInfo(@PathVariable(value = "userId", required = false) String userId) { SysUserEntity user = userService.selectUserById(userId); @@ -154,7 +199,10 @@ public class SysUserController { return R.ok(map); } - @ApiOperation(value = "获取个人信息") + @ApiOperation(value = "获取个人信息", notes = "获取当前登录用户的个人信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class) + }) @GetMapping(value = "/profile") public R getProfile() { Map map = new HashMap<>(8); @@ -164,10 +212,14 @@ public class SysUserController { return R.ok(map); } - @ApiOperation(value = "用户头像上传") + @ApiOperation(value = "用户头像上传", notes = "上传用户头像图片") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class), + @ApiResponse(code = 500, message = "上传头像异常") + }) @Log(title = "用户头像上传", businessType = BusinessType.UPDATE) @PostMapping("/profile/avatar") - public R uploadAvatar(@RequestParam("avatarfile") MultipartFile file) throws Exception { + public R uploadAvatar(@ApiParam(value = "头像文件", required = true) @RequestParam("avatarfile") MultipartFile file) throws Exception { if (!file.isEmpty()) { String avatar = ossFileService.upload(file.getInputStream(), "avatar", file.getOriginalFilename()); if (userService.updateUserAvatar(SecurityUtils.getUserId(), avatar)) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/controller/UserOnlineController.java b/play-admin/src/main/java/com/starry/admin/modules/system/controller/UserOnlineController.java index ed75bfb..4bc272c 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/controller/UserOnlineController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/controller/UserOnlineController.java @@ -13,6 +13,13 @@ import com.starry.common.enums.BusinessType; import com.starry.common.redis.RedisCache; import com.starry.common.result.R; import com.starry.common.utils.StringUtils; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiImplicitParam; +import io.swagger.annotations.ApiImplicitParams; +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.web.bind.annotation.*; @@ -26,6 +33,7 @@ import java.util.List; * 在线用户监控 * @since 2022/10/18 */ +@Api(tags = "在线用户监控", description = "系统在线用户监控相关接口") @RestController @RequestMapping("/monitor/online") public class UserOnlineController { @@ -35,6 +43,14 @@ public class UserOnlineController { @Resource private UserOnlineService userOnlineService; + @ApiOperation(value = "查询在线用户列表", notes = "根据IP地址和用户名查询在线用户") + @ApiImplicitParams({ + @ApiImplicitParam(name = "ipaddr", value = "IP地址", dataType = "String", paramType = "query"), + @ApiImplicitParam(name = "userName", value = "用户名", dataType = "String", paramType = "query") + }) + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = UserOnline.class, responseContainer = "Page") + }) @PreAuthorize("@customSs.hasPermission('monitor:online:list')") @GetMapping("/list") public R list(String ipaddr, String userName) { @@ -67,6 +83,11 @@ public class UserOnlineController { /** * 强退用户 */ + @ApiOperation(value = "强制退出用户", notes = "强制指定token的用户下线") + @ApiImplicitParam(name = "tokenId", value = "用户token", required = true, dataType = "String", paramType = "path") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PreAuthorize("@customSs.hasPermission('monitor:online:forceLogout')") @Log(title = "在线用户", businessType = BusinessType.FORCE) @DeleteMapping("/{tokenId}") diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/module/entity/SysLoginLogVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/module/entity/SysLoginLogVo.java index dbeea8a..f6b0fbd 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/module/entity/SysLoginLogVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/module/entity/SysLoginLogVo.java @@ -5,6 +5,8 @@ import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableId; import com.starry.admin.modules.system.vo.StatusConverter; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -18,6 +20,7 @@ import java.util.Date; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "登录日志查询参数", description = "系统访问日志查询条件") public class SysLoginLogVo extends BasePageEntity { private static final long serialVersionUID = 1L; @@ -25,53 +28,62 @@ public class SysLoginLogVo extends BasePageEntity { /** * 主键ID */ + @ApiModelProperty(value = "日志ID", example = "1", notes = "主键ID") @TableId(value = "login_id", type = IdType.AUTO) private Long loginId; /** * 用户账号 */ + @ApiModelProperty(value = "用户账号", example = "admin", notes = "登录的用户账号，支持模糊查询") @ExcelProperty(value = "用户账号") private String userCode; /** * 登录IP地址 */ + @ApiModelProperty(value = "登录IP", example = "127.0.0.1", notes = "用户登录的IP地址") @ExcelProperty(value = "登录IP地址") private String ipaddr; /** * 登录地点 */ + @ApiModelProperty(value = "登录地点", example = "北京", notes = "根据IP解析的登录地理位置") @ExcelProperty(value = "登录地点") private String loginLocation; /** * 浏览器类型 */ + @ApiModelProperty(value = "浏览器类型", example = "Chrome", notes = "用户使用的浏览器") @ExcelProperty(value = "浏览器类型") private String browser; /** * 操作系统 */ + @ApiModelProperty(value = "操作系统", example = "Windows 10", notes = "用户使用的操作系统") @ExcelProperty(value = "操作系统") private String os; /** * 提示消息 */ + @ApiModelProperty(value = "提示消息", example = "登录成功", notes = "登录操作的提示信息") private String msg; /** * 登录状态（0成功 1失败） */ + @ApiModelProperty(value = "登录状态", example = "0", notes = "0:成功 1:失败") @ExcelProperty(value = "登录状态", converter = StatusConverter.class) private Integer status; /** * 访问时间 */ + @ApiModelProperty(value = "登录时间", example = "2023-01-01 00:00:00", notes = "用户登录的时间") private Date loginTime; diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/LoginVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/LoginVo.java index ed7351a..2d73099 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/LoginVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/LoginVo.java @@ -1,5 +1,6 @@ package com.starry.admin.modules.system.vo; +import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @@ -10,19 +11,21 @@ import java.io.Serializable; * @since 2021/9/6 */ @Data +@ApiModel(value = "登录参数", description = "用户登录的请求参数") public class LoginVo implements Serializable { - @ApiModelProperty(value = "用户名") + @ApiModelProperty(value = "用户名", required = true, example = "admin", notes = "登录账号") private String userName; - @ApiModelProperty(value = "密码") + @ApiModelProperty(value = "密码", required = true, example = "123456", notes = "登录密码") private String passWord; - @ApiModelProperty(value = "验证码随机字符串") + @ApiModelProperty(value = "验证码随机字符串", example = "abc123", notes = "验证码请求时返回的唯一标识") private String nonceStr; - @ApiModelProperty(value = "验证值") + @ApiModelProperty(value = "验证码", example = "1234", notes = "用户输入的验证码") private String value; + @ApiModelProperty(value = "租户标识", example = "tenant1", notes = "多租户模式下的租户唯一标识") private String tenantKey; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/MetaVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/MetaVo.java index 489fdfc..d39c351 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/MetaVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/MetaVo.java @@ -2,6 +2,7 @@ package com.starry.admin.modules.system.vo; import com.starry.common.constant.Constants; +import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import org.apache.commons.lang3.StringUtils; @@ -12,30 +13,31 @@ import org.apache.commons.lang3.StringUtils; * @since 2022/7/6 */ @Data +@ApiModel(value = "路由元数据", description = "路由显示信息配置") public class MetaVo { /** * 设置该路由在侧边栏和面包屑中展示的名字 */ - @ApiModelProperty(value = "设置该路由在侧边栏和面包屑中展示的名字") + @ApiModelProperty(value = "路由标题", example = "系统管理", notes = "设置该路由在侧边栏和面包屑中展示的名字") private String title; /** * 设置该路由的图标，对应路径src/assets/icons/svg */ - @ApiModelProperty(value = "设置该路由的图标，对应路径src/assets/icons/svg") + @ApiModelProperty(value = "路由图标", example = "system", notes = "设置该路由的图标，对应路径src/assets/icons/svg") private String icon; /** * 设置为true，则不会被 缓存 */ - @ApiModelProperty(value = "设置为true，则不会被 缓存") + @ApiModelProperty(value = "是否缓存", example = "false", notes = "设置为true，则不会被缓存") private boolean noCache; /** * 内链地址（http(s)://开头） */ - @ApiModelProperty(value = "内链地址（http(s)://开头）") + @ApiModelProperty(value = "内链地址", example = "https://www.example.com", notes = "内链地址（http(s)://开头）") private String link; public MetaVo(String title, String icon) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/RouterVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/RouterVo.java index 7261cd4..f749ff2 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/RouterVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/RouterVo.java @@ -1,5 +1,6 @@ package com.starry.admin.modules.system.vo; +import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @@ -11,35 +12,37 @@ import java.util.List; * @since 2022/7/6 */ @Data +@ApiModel(value = "路由信息", description = "前端路由配置信息") public class RouterVo { - @ApiModelProperty(value = "路由名字") + @ApiModelProperty(value = "路由名字", example = "System", notes = "路由的唯一标识名称") private String name; - @ApiModelProperty(value = "路由地址") + @ApiModelProperty(value = "路由地址", example = "/system", notes = "URL路径") private String path; - @ApiModelProperty(value = "是否隐藏路由，当设置 true 的时候该路由不会再侧边栏出现") + @ApiModelProperty(value = "是否隐藏路由", example = "false", notes = "当设置为true时该路由不会在侧边栏出现") private boolean hidden; - @ApiModelProperty(value = "重定向地址，当设置 noRedirect 的时候该路由在面包屑导航中不可被点击") + @ApiModelProperty(value = "重定向地址", example = "noRedirect", notes = "当设置noRedirect时该路由在面包屑导航中不可被点击") private String redirect; - @ApiModelProperty(value = "组件地址") + @ApiModelProperty(value = "组件地址", example = "Layout", notes = "对应的前端组件路径") private String component; /** * 路由参数：如 {"id": 1, "name": "ry"} */ + @ApiModelProperty(value = "路由参数", example = "{\"id\": 1, \"name\": \"admin\"}", notes = "路由参数，JSON格式") private String routerQuery; - @ApiModelProperty(value = "当你一个路由下面的 children 声明的路由大于1个时，自动会变成嵌套的模式--如组件页面") + @ApiModelProperty(value = "是否总是显示", example = "true", notes = "当一个路由下面的children声明的路由大于1个时，自动会变成嵌套的模式") private Boolean alwaysShow; - @ApiModelProperty(value = "其他元素") + @ApiModelProperty(value = "路由元信息", notes = "路由的其他配置信息") private MetaVo meta; - @ApiModelProperty(value = "子路由") + @ApiModelProperty(value = "子路由", notes = "子路由配置信息") private List children; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysOperationLogVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysOperationLogVo.java index 60e2f7b..58fa7c9 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysOperationLogVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysOperationLogVo.java @@ -5,6 +5,7 @@ import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableField; import com.baomidou.mybatisplus.annotation.TableId; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -19,6 +20,7 @@ import java.util.Date; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "操作日志查询参数", description = "系统操作日志查询条件") public class SysOperationLogVo extends BasePageEntity { private static final long serialVersionUID = 1L; @@ -26,100 +28,118 @@ public class SysOperationLogVo extends BasePageEntity { /** * 主键ID */ - @ApiModelProperty("主键ID") + @ApiModelProperty(value = "日志ID", example = "1", notes = "主键ID") @TableId(value = "oper_id", type = IdType.AUTO) private Long operId; /** * 模块标题 */ + @ApiModelProperty(value = "模块标题", example = "用户管理", notes = "操作的系统模块") @ExcelProperty(value = "系统模块") private String title; /** * 业务类型（0其它 1新增 2修改 3删除） */ + @ApiModelProperty(value = "业务类型", example = "1", notes = "0:其它 1:新增 2:修改 3:删除") private Integer businessType; /** * 业务类型数组 */ + @ApiModelProperty(value = "业务类型数组", notes = "多个业务类型的集合") @TableField(exist = false) private Integer[] businessTypes; /** * 方法名称 */ + @ApiModelProperty(value = "方法名称", example = "com.starry.admin.modules.system.controller.SysUserController.create", notes = "调用的方法名") @ExcelProperty(value = "方法名称") private String method; /** * 请求方式 */ + @ApiModelProperty(value = "请求方式", example = "POST", notes = "HTTP请求方式") private String requestMethod; /** * 操作类别（0其它 1后台用户 2手机端用户） */ + @ApiModelProperty(value = "操作类别", example = "1", notes = "0:其它 1:后台用户 2:手机端用户") private Integer operatorType; /** * 操作人员 */ + @ApiModelProperty(value = "操作人员", example = "admin", notes = "执行操作的用户账号") private String operName; /** * 请求URL */ + @ApiModelProperty(value = "请求URL", example = "/system/user/create", notes = "请求的接口地址") private String operUrl; /** * 主机地址 */ + @ApiModelProperty(value = "主机地址", example = "127.0.0.1", notes = "请求的IP地址") private String operIp; /** * 操作地点 */ + @ApiModelProperty(value = "操作地点", example = "北京", notes = "根据IP解析的地理位置") private String operLocation; /** * 请求参数 */ + @ApiModelProperty(value = "请求参数", notes = "请求的参数内容") private String operParam; /** * 返回参数 */ + @ApiModelProperty(value = "返回参数", notes = "接口返回的结果") private String jsonResult; /** * 操作状态（0正常 1异常） */ + @ApiModelProperty(value = "操作状态", example = "0", notes = "0:正常 1:异常") private Integer status; /** * 错误消息 */ + @ApiModelProperty(value = "错误消息", example = "权限不足", notes = "操作失败时的错误信息") private String errorMsg; /** * 操作时间 */ + @ApiModelProperty(value = "操作时间", example = "2023-01-01 00:00:00", notes = "操作的时间") private Date operTime; /** * 部门名称 */ + @ApiModelProperty(value = "部门名称", example = "研发部", notes = "操作人员所属部门") private String deptName; /** * 部门id */ + @ApiModelProperty(value = "部门ID", example = "1", notes = "操作人员所属部门ID") private Long deptId; /** * 租户ID */ + @ApiModelProperty(value = "租户ID", example = "1", notes = "所属租户ID") private Long tenantId; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysRoleAddVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysRoleAddVo.java index 64d8b71..21b5766 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysRoleAddVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysRoleAddVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.system.vo; import com.starry.admin.modules.system.module.entity.SysRoleEntity; import com.starry.common.domain.BaseEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -13,43 +15,56 @@ import java.util.Set; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "角色添加参数", description = "新增系统角色的请求参数") public class SysRoleAddVo extends BaseEntity { private static final long serialVersionUID = 1L; + @ApiModelProperty(value = "角色ID", hidden = true, notes = "新增时无需填写，系统自动生成") private Long roleId; @NotBlank(message = "角色名称不能为空") + @ApiModelProperty(value = "角色名称", required = true, example = "管理员", notes = "角色显示名称") private String roleName; + @ApiModelProperty(value = "角色描述", example = "系统管理员", notes = "角色的详细描述") private String description; + @ApiModelProperty(value = "角色状态", example = "0", notes = "0-正常，1-停用") private Integer status; + @ApiModelProperty(value = "数据权限范围", example = "1", notes = "1:全部数据权限 2:自定数据权限 3:本部门数据权限 4:本部门及以下数据权限 5:仅本人数据权限") private String dataScope; + @ApiModelProperty(value = "菜单树选择项是否关联显示", example = "true") private boolean menuCheckStrictly; + @ApiModelProperty(value = "部门树选择项是否关联显示", example = "true") private boolean deptCheckStrictly; + @ApiModelProperty(value = "权限字符", required = true, example = "admin", notes = "角色权限字符串") private String roleKey; + @ApiModelProperty(value = "租户ID", example = "1", notes = "角色所属租户ID") private Long tenantId; /** * 菜单组 */ + @ApiModelProperty(value = "菜单ID数组", notes = "角色关联的菜单ID列表") private Long[] menuIds; /** * 部门组（数据权限） */ + @ApiModelProperty(value = "部门ID数组", notes = "角色关联的部门ID列表，用于数据权限") private Long[] deptIds; /** * 角色菜单权限 */ + @ApiModelProperty(value = "角色权限集合", notes = "角色拥有的菜单权限列表") private Set permissions; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserEntityListVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserEntityListVo.java index ecf3121..ede4c0a 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserEntityListVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserEntityListVo.java @@ -2,6 +2,8 @@ package com.starry.admin.modules.system.vo; import com.starry.admin.modules.clerk.module.entity.PlayClerkUserInfoEntity; import com.starry.admin.modules.system.module.entity.SysUserEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.AllArgsConstructor; import lombok.Data; import lombok.EqualsAndHashCode; @@ -15,18 +17,24 @@ import java.util.List; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "用户列表展示对象", description = "系统用户列表格式化展示的对象") public class SysUserEntityListVo extends SysUserEntity { + @ApiModelProperty(value = "角色列表", notes = "用户拥有的角色信息列表") private List roleVoList; + @ApiModelProperty(value = "店员信息", notes = "关联的店员详细信息") private PlayClerkUserInfoEntity clerkUserInfo; @Data @AllArgsConstructor + @ApiModel(value = "角色信息对象", description = "用户所属角色的简要信息") public static class RoleVo { + @ApiModelProperty(value = "角色名称", example = "管理员") private String roleName; + @ApiModelProperty(value = "角色对应的用户名", example = "admin") private String roleUserName; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserQueryVo.java index f5db5db..b0c4fa3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/SysUserQueryVo.java @@ -3,6 +3,8 @@ package com.starry.admin.modules.system.vo; import com.starry.admin.modules.system.module.entity.SysDeptEntity; import com.starry.admin.modules.system.module.entity.SysRoleEntity; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -16,49 +18,68 @@ import java.util.List; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "系统用户查询参数", description = "查询系统用户的条件参数") public class SysUserQueryVo extends BasePageEntity { private static final long serialVersionUID = 1L; + @ApiModelProperty(value = "用户ID", example = "1") private Long userId; + @ApiModelProperty(value = "用户类型", example = "1", notes = "1:admin;2:会员") private Integer userType; + @ApiModelProperty(value = "用户名", example = "admin", notes = "登录账号，支持模糊查询") private String userCode; + @ApiModelProperty(value = "密码", hidden = true) private String passWord; + @ApiModelProperty(value = "姓名", example = "张三", notes = "用户真实姓名，支持模糊查询") private String realName; + @ApiModelProperty(value = "用户昵称", example = "小张", notes = "用户昵称，支持模糊查询") private String userNickname; + @ApiModelProperty(value = "邮箱", example = "test@example.com") private String userEmail; - + @ApiModelProperty(value = "头像", example = "https://example.com/avatar.jpg") private String avatar; + @ApiModelProperty(value = "手机号码", example = "13800138000") private String mobile; + @ApiModelProperty(value = "性别", example = "1", notes = "1:男;2:女;0:未知") private Integer sex; + @ApiModelProperty(value = "出生日期", example = "1990-01-01") private Date birthday; + @ApiModelProperty(value = "状态", example = "0", notes = "0:正常;1:停用") private Integer status; + @ApiModelProperty(value = "最后登录时间") private Date lastLoginTime; + @ApiModelProperty(value = "最后登录IP", example = "192.168.1.1") private String lastLoginIp; + @ApiModelProperty(value = "部门ID", example = "1") private Long deptId; + @ApiModelProperty(value = "租户ID", example = "1") private Long tenantId; + @ApiModelProperty(value = "角色列表", notes = "用户关联的角色信息") private List roles; + @ApiModelProperty(value = "角色ID数组", notes = "用户关联的角色ID列表") private Long[] roleIds; - + @ApiModelProperty(value = "部门信息", notes = "用户所属部门详情") private SysDeptEntity dept; + @ApiModelProperty(value = "角色ID", example = "1", notes = "用于查询已分配或未分配指定角色的用户") private Long roleId; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserMobileParam.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserMobileParam.java index de41732..518d86a 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserMobileParam.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserMobileParam.java @@ -1,19 +1,31 @@ package com.starry.admin.modules.system.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; +import javax.validation.constraints.NotBlank; +import javax.validation.constraints.Pattern; + /** * @Author: huchuansai * @Date: 2024/6/14 3:05 PM * @Description: */ @Data +@ApiModel(value = "修改手机号参数", description = "用户修改手机号的请求参数") public class UpdateUserMobileParam { + @ApiModelProperty(value = "用户ID", notes = "要修改手机号的用户ID，不传则修改当前登录用户") private String userId; + @NotBlank(message = "手机号不能为空") + @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确") + @ApiModelProperty(value = "新手机号", required = true, example = "13800138000", notes = "用户的新手机号") private String mobile; + @NotBlank(message = "验证码不能为空") + @ApiModelProperty(value = "短信验证码", required = true, example = "123456", notes = "发送到新手机号的验证码") private String smsCode; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserPasswordParam.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserPasswordParam.java index 3bd8509..5d4e40f 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserPasswordParam.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UpdateUserPasswordParam.java @@ -1,17 +1,25 @@ package com.starry.admin.modules.system.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; +import javax.validation.constraints.NotBlank; + /** * @Author: huchuansai * @Date: 2024/6/14 3:05 PM * @Description: */ @Data +@ApiModel(value = "修改密码参数", description = "用户修改密码的请求参数") public class UpdateUserPasswordParam { + @ApiModelProperty(value = "用户ID", notes = "要修改密码的用户ID，不传则修改当前登录用户") private String userId; + @NotBlank(message = "密码不能为空") + @ApiModelProperty(value = "新密码", required = true, notes = "用户的新密码") private String password; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserAddParam.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserAddParam.java index a29ce24..ffc5d13 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserAddParam.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserAddParam.java @@ -1,8 +1,11 @@ package com.starry.admin.modules.system.vo; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotEmpty; +import javax.validation.constraints.Pattern; /** * @Author: huchuansai @@ -10,15 +13,20 @@ import javax.validation.constraints.NotEmpty; * @Description: */ @Data +@ApiModel(value = "用户添加参数", description = "新增系统用户的请求参数") public class UserAddParam { @NotEmpty(message = "请指定店员") + @ApiModelProperty(value = "店员ID", required = true, notes = "关联的店员ID") private String clerkId; @NotEmpty(message = "请指定手机号") + @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确") + @ApiModelProperty(value = "手机号", required = true, example = "13800138000", notes = "用户手机号，作为登录账号") private String mobile; @NotEmpty(message = "请指定短信验证码") + @ApiModelProperty(value = "短信验证码", required = true, example = "123456", notes = "发送到手机的验证码") private String smsCode; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserQueryVo.java index 6496119..33cc262 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/system/vo/UserQueryVo.java @@ -2,6 +2,7 @@ package com.starry.admin.modules.system.vo; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -12,14 +13,15 @@ import lombok.EqualsAndHashCode; */ @EqualsAndHashCode(callSuper = true) @Data +@ApiModel(value = "用户查询参数", description = "系统用户分页查询的条件参数") public class UserQueryVo extends BasePageEntity { - @ApiModelProperty(value = "用户id") + @ApiModelProperty(value = "用户ID", example = "1", notes = "用户唯一标识") private String userId; - @ApiModelProperty(value = "用户名") + @ApiModelProperty(value = "用户名", example = "admin", notes = "登录账号，支持模糊查询") private String userCode; - @ApiModelProperty(value = "姓名") + @ApiModelProperty(value = "姓名", example = "张三", notes = "用户真实姓名，支持模糊查询") private String realName; } diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxArticleController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxArticleController.java index 96c0fa0..8068129 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxArticleController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxArticleController.java @@ -17,6 +17,12 @@ import com.starry.admin.modules.weichat.entity.article.PlayClerkArticleFollowCus import com.starry.admin.modules.weichat.service.WxCustomUserService; 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 lombok.extern.slf4j.Slf4j; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.*; @@ -30,6 +36,7 @@ import java.time.LocalDateTime; * @author admin * @since 2024/5/20 下午11:19 **/ +@Api(tags = "微信文章动态接口", description = "微信端文章动态相关接口") @Slf4j @RestController @RequestMapping("/wx/article") @@ -52,9 +59,13 @@ public class WxArticleController { /** * 店员新增动态 */ + @ApiOperation(value = "店员新增动态", notes = "店员发布新的动态文章") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @ClerkUserLogin @PostMapping("/clerk/add") - public R clerkAdd(@Validated @RequestBody PlayClerkAddArticleVo vo) { + public R clerkAdd(@ApiParam(value = "动态信息", required = true) @Validated @RequestBody PlayClerkAddArticleVo vo) { vo.setClerkId(ThreadLocalRequestDetail.getClerkUserInfo().getId()); playClerkArticleInfoService.create(ConvertUtil.entityToVo(vo, PlayClerkArticleInfoEntity.class)); return R.ok("成功"); @@ -64,6 +75,11 @@ public class WxArticleController { /** * 店员删除 */ + @ApiOperation(value = "店员删除动态", notes = "店员删除自己发布的动态") + @ApiImplicitParam(name = "id", value = "动态ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @ClerkUserLogin @GetMapping("/clerk/deleteById") public R clerkDeleteById(@RequestParam("id") String id) { @@ -75,9 +91,13 @@ public class WxArticleController { /** * 店员分页查询本人动态列表 */ + @ApiOperation(value = "店员查询动态", notes = "店员分页查询自己的动态列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkArticleInfoEntity.class, responseContainer = "Page") + }) @ClerkUserLogin @PostMapping("/clerk/listByPage") - public R clerkListByPage(@Validated @RequestBody PlayClerkArticleQueryVo vo) { + public R clerkListByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkArticleQueryVo vo) { vo.setClerkId(ThreadLocalRequestDetail.getClerkUserInfo().getId()); return R.ok(playClerkArticleInfoService.selectByPage(vo,true)); } @@ -86,8 +106,12 @@ public class WxArticleController { /** * 顾客查询动态列表 */ + @ApiOperation(value = "顾客查询动态列表", notes = "顾客分页查询所有动态列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkArticleInfoEntity.class, responseContainer = "Page") + }) @PostMapping("/custom/listByPage") - public R customListByPage(@Validated @RequestBody PlayClerkArticleCustomQueryVo vo) { + public R customListByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkArticleCustomQueryVo vo) { vo.setFollowState("0"); return R.ok(playClerkArticleInfoService.customSelectByPage(vo,customUserService.getLoginUserId())); } @@ -95,9 +119,13 @@ public class WxArticleController { /** * 顾客查询已收藏动态列表 */ + @ApiOperation(value = "查询收藏动态", notes = "顾客查询已收藏的动态列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkArticleInfoEntity.class, responseContainer = "Page") + }) @CustomUserLogin @PostMapping("/custom/listFollowByPage") - public R customListFollowByPage(@Validated @RequestBody PlayClerkArticleCustomQueryVo vo) { + public R customListFollowByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayClerkArticleCustomQueryVo vo) { vo.setFollowState("1"); return R.ok(playClerkArticleInfoService.customSelectByPage(vo, customUserService.getLoginUserId())); } @@ -108,6 +136,11 @@ public class WxArticleController { * @param id 店员ID * @return 店员动态 */ + @ApiOperation(value = "获取店员动态", notes = "根据店员ID查询该店员的动态") + @ApiImplicitParam(name = "id", value = "店员ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkArticleInfoEntity.class, responseContainer = "Page") + }) @GetMapping("/custom/queryByClerkId") public R queryTrendsById(@RequestParam("id") String id) { PlayClerkUserInfoEntity entity = playClerkUserInfoService.selectById(id); @@ -120,9 +153,13 @@ public class WxArticleController { /** * 顾客查询已收藏动态列表 */ + @ApiOperation(value = "更新点赞状态", notes = "顾客更新对动态的点赞状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @CustomUserLogin @PostMapping("/custom/updateGreedState") - public R customUpdateGreedState(@Validated @RequestBody PlayClerkArticleFollowCustomGreedStateEditStateVo vo) { + public R customUpdateGreedState(@ApiParam(value = "点赞信息", required = true) @Validated @RequestBody PlayClerkArticleFollowCustomGreedStateEditStateVo vo) { PlayClerkArticleInfoEntity articleInfoEntity = playClerkArticleInfoService.selectPlayClerkArticleInfoById(vo.getId()); PlayCustomArticleInfoEntity entity = playCustomArticleInfoService.selectByArticleId(articleInfoEntity.getId(), ThreadLocalRequestDetail.getCustomUserInfo().getId(), "0"); if (entity == null) { @@ -138,9 +175,13 @@ public class WxArticleController { return R.ok("成功"); } + @ApiOperation(value = "更新收藏状态", notes = "顾客更新对动态的收藏状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @CustomUserLogin @PostMapping("/custom/updateFollowState") - public R customUpdateFollowState(@Validated @RequestBody PlayClerkArticleFollowCustomFollowStateEditStateVo vo) { + public R customUpdateFollowState(@ApiParam(value = "收藏信息", required = true) @Validated @RequestBody PlayClerkArticleFollowCustomFollowStateEditStateVo vo) { PlayClerkArticleInfoEntity articleInfoEntity = playClerkArticleInfoService.selectPlayClerkArticleInfoById(vo.getId()); PlayCustomArticleInfoEntity entity = playCustomArticleInfoService.selectByArticleId(articleInfoEntity.getId(), ThreadLocalRequestDetail.getCustomUserInfo().getId(), "1"); if (entity == null) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkCommodityController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkCommodityController.java index 023b737..8b1e94a 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkCommodityController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkCommodityController.java @@ -12,6 +12,11 @@ import com.starry.admin.modules.shop.service.IPlayCommodityAndLevelInfoService; import com.starry.admin.modules.shop.service.IPlayCommodityInfoService; import com.starry.admin.modules.weichat.entity.PlayCommodityReturnVo; 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.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -30,6 +35,7 @@ import java.util.stream.Collectors; * @author admin * @since 2024/5/29 上午6:24 **/ +@Api(tags = "微信店员商品接口", description = "微信端店员商品相关接口") @Slf4j @RestController @RequestMapping("/wx/commodity/") @@ -48,6 +54,11 @@ public class WxClerkCommodityController { IPlayClerkCommodityService playClerkCommodityService; + @ApiOperation(value = "根据等级查询商品", notes = "根据等级ID查询对应等级的所有商品") + @ApiImplicitParam(name = "id", value = "等级ID", dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCommodityReturnVo.class, responseContainer = "List") + }) @GetMapping("/custom/queryClerkAllCommodityByLevel") public R queryClerkAllCommodityByLevel(@RequestParam("id") String levelId) { List levelInfoEntities = iPlayCommodityAndLevelInfoService.selectAll(); @@ -66,6 +77,12 @@ public class WxClerkCommodityController { * * @return 店员所有服务项目 */ + @ApiOperation(value = "查询店员商品", notes = "根据店员ID查询该店员提供的所有商品服务") + @ApiImplicitParam(name = "id", value = "店员ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCommodityReturnVo.class, responseContainer = "List"), + @ApiResponse(code = 500, message = "请求参数异常,id不能为空") + }) @GetMapping("/custom/queryClerkAllCommodity") public R customQueryClerkAllCommodity(@RequestParam("id") String clerkId) { if (clerkId == null || clerkId.isEmpty()) { @@ -87,6 +104,10 @@ public class WxClerkCommodityController { * * @return 店员所有服务项目 */ + @ApiOperation(value = "店员查询自己的商品", notes = "当前登录店员查询自己提供的所有商品服务") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCommodityReturnVo.class, responseContainer = "List") + }) @ClerkUserLogin @GetMapping("/clerk/queryAllCommodity") public R clerkQueryAllCommodity() { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkController.java index df7f0ba..bd6c876 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkController.java @@ -39,6 +39,11 @@ import com.starry.common.redis.RedisCache; import com.starry.common.result.R; import com.starry.common.utils.ConvertUtil; import com.starry.common.utils.VerificationCodeUtils; +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 lombok.extern.slf4j.Slf4j; import org.springframework.transaction.annotation.Transactional; import org.springframework.validation.annotation.Validated; @@ -55,6 +60,7 @@ import java.util.concurrent.TimeUnit; /** * @author admin */ +@Api(tags = "微信店员接口", description = "微信端店员相关接口") @Slf4j @RestController @RequestMapping("/wx/clerk/") @@ -112,9 +118,13 @@ public class WxClerkController { /** * 店员获取个人业绩信息 */ + @ApiOperation(value = "查询店员业绩", notes = "店员获取个人业绩信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @ClerkUserLogin @PostMapping("/user/queryPerformanceInfo") - public R queryPerformanceInfo(@Validated @RequestBody PlayClerkWxPerformanceInfoQueryVo vo) { + public R queryPerformanceInfo(@ApiParam(value = "业绩查询条件", required = true) @Validated @RequestBody PlayClerkWxPerformanceInfoQueryVo vo) { PlayClerkUserInfoEntity entity = clerkUserInfoService.selectById(ThreadLocalRequestDetail.getClerkUserInfo().getId()); List clerkLevelInfoEntity = playClerkLevelInfoService.selectAll(); List orderInfoEntities = playOrderInfoService.clerkSelectOrderInfoList(entity.getId(), vo.getStartTime(), vo.getEndTime()); @@ -126,6 +136,10 @@ public class WxClerkController { /** * 店员获取个人等级信息 */ + @ApiOperation(value = "查询店员等级", notes = "店员获取个人等级信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkLevelInfoReturnVo.class) + }) @ClerkUserLogin @GetMapping("/user/queryLevelInfo") public R queryLevelInfo() { @@ -149,6 +163,11 @@ public class WxClerkController { /** * 店员获取个人信息 */ + @ApiOperation(value = "查询店员信息", notes = "店员获取个人详细信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserInfoResultVo.class), + @ApiResponse(code = 500, message = "用户不存在") + }) @ClerkUserLogin @GetMapping("/user/queryById") public R queryById() { @@ -160,9 +179,13 @@ public class WxClerkController { } + @ApiOperation(value = "发送验证码", notes = "店员绑定手机号发送验证码") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class) + }) @ClerkUserLogin @PostMapping("/user/sendCode") - public R sendCode(@Validated @RequestBody PlayClerkUserSendCodeVo vo) { + public R sendCode(@ApiParam(value = "发送验证码信息", required = true) @Validated @RequestBody PlayClerkUserSendCodeVo vo) { String codeKey = "login_codes:" + SecurityUtils.getTenantId() + "_" + SecureUtil.md5(vo.getAreaCode() + vo.getPhone()); String code = VerificationCodeUtils.getVerificationCode(4); redisCache.setCacheObject(codeKey, code, 5L, TimeUnit.MINUTES); @@ -170,9 +193,14 @@ public class WxClerkController { return R.ok(code); } + @ApiOperation(value = "绑定手机号", notes = "店员绑定手机号") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "验证码错误") + }) @ClerkUserLogin @PostMapping("/user/bindCode") - public R bindCode(@Validated @RequestBody PlayClerkUserBindCodeVo vo) { + public R bindCode(@ApiParam(value = "绑定验证码信息", required = true) @Validated @RequestBody PlayClerkUserBindCodeVo vo) { String codeKey = "login_codes:" + SecurityUtils.getTenantId() + "_" + SecureUtil.md5(vo.getAreaCode() + vo.getPhone()); String code = redisCache.getCacheObject(codeKey); if (code == null || !code.equals(vo.getCode())) { @@ -190,10 +218,17 @@ public class WxClerkController { return R.ok("成功"); } + @ApiOperation(value = "店员申请", notes = "用户申请成为店员") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "系统错误，用户不存在"), + @ApiResponse(code = 500, message = "当前用户已经是店员"), + @ApiResponse(code = 500, message = "已有申请未审核") + }) @ClerkUserLogin @PostMapping("/user/add") @Transactional(rollbackFor = Exception.class) - public R userAdd(@Validated @RequestBody PlayClerkUserByWxAddVo vo) { + public R userAdd(@ApiParam(value = "店员申请信息", required = true) @Validated @RequestBody PlayClerkUserByWxAddVo vo) { String clerkId = ThreadLocalRequestDetail.getClerkUserInfo().getId(); PlayClerkUserInfoEntity userInfo = playClerkUserInfoService.selectById(clerkId); if (userInfo == null) { @@ -218,9 +253,13 @@ public class WxClerkController { } + @ApiOperation(value = "更新头像", notes = "店员更新头像") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @ClerkUserLogin @PostMapping("/user/updateAvatar") - public R updateAvatar(@Validated @RequestBody PlayClerkUserAvatarVo vo) { + public R updateAvatar(@ApiParam(value = "头像信息", required = true) @Validated @RequestBody PlayClerkUserAvatarVo vo) { PlayClerkUserInfoEntity userInfo = ThreadLocalRequestDetail.getClerkUserInfo(); // PlayClerkDataReviewInfoEntity entity = playClerkDataReviewInfoService.queryByClerkId(userInfo.getId(), "1", "0"); // if (entity != null) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkLeveController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkLeveController.java index 261c7b4..468e0e3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkLeveController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkLeveController.java @@ -4,6 +4,10 @@ import com.starry.admin.modules.clerk.module.entity.PlayClerkLevelInfoEntity; import com.starry.admin.modules.clerk.service.IPlayClerkLevelInfoService; import com.starry.admin.modules.weichat.entity.level.PlayClerkLevelReturnVo; import com.starry.common.result.R; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -19,6 +23,7 @@ import java.util.List; * @author admin * @since 2024/5/29 上午6:24 **/ +@Api(tags = "微信店员等级接口", description = "微信端店员等级相关接口") @Slf4j @RestController @RequestMapping("/wx/level/") @@ -33,6 +38,10 @@ public class WxClerkLeveController { * * @return 店员所有等级列表 */ + @ApiOperation(value = "查询店员等级列表", notes = "顾客查询所有店员等级列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkLevelReturnVo.class, responseContainer = "List") + }) @GetMapping("/custom/queryClerkAllLevel") public R customQueryClerkAllLevel() { List list = playClerkLevelInfoService.selectAll(); diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkTypeController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkTypeController.java index f291459..5204312 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkTypeController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkTypeController.java @@ -4,6 +4,10 @@ import com.baomidou.mybatisplus.core.toolkit.Wrappers; import com.starry.admin.modules.clerk.module.entity.PlayClerkTypeInfoEntity; import com.starry.admin.modules.clerk.service.IPlayClerkTypeInfoService; import com.starry.common.result.R; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -18,6 +22,7 @@ import java.util.List; * @author admin * @since 2024/5/29 上午6:24 **/ +@Api(tags = "微信店员类型接口", description = "微信端店员类型相关接口") @Slf4j @RestController @RequestMapping("/wx/clerk/type") @@ -32,6 +37,10 @@ public class WxClerkTypeController { * * @return 店员所有等级列表 */ + @ApiOperation(value = "查询店员类型列表", notes = "查询所有店员类型列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkTypeInfoEntity.class, responseContainer = "List") + }) @GetMapping("/list") public R clerkTypeList() { List list = clerkTypeInfoService.list(Wrappers.lambdaQuery(PlayClerkTypeInfoEntity.class).eq(PlayClerkTypeInfoEntity::getHomeDisplayed,1).orderByDesc(PlayClerkTypeInfoEntity::getSort)); diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkWagesController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkWagesController.java index 73329c8..7ca5835 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkWagesController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxClerkWagesController.java @@ -16,6 +16,11 @@ import com.starry.admin.modules.weichat.entity.wages.*; 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.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.*; @@ -31,6 +36,7 @@ import java.util.List; * @author admin * @since 2024/5/31 16:18 **/ +@Api(tags = "微信店员工资接口", description = "微信端店员工资相关接口") @Slf4j @RestController @RequestMapping("/wx/wages") @@ -52,6 +58,10 @@ public class WxClerkWagesController { * @author admin * @since 2024/5/31 16:20 **/ + @ApiOperation(value = "查询未结算工资", notes = "店员查询本人未结算工资") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = ClerkUnsettledWagesReturnVo.class) + }) @ClerkUserLogin @GetMapping("clerk/queryUnsettledWages") public R clerkQueryUnsettledWages() { @@ -72,6 +82,10 @@ public class WxClerkWagesController { * @author admin * @since 2024/5/31 16:20 **/ + @ApiOperation(value = "查询当期工资", notes = "店员查询本人当期工资") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = ClerkCurrentPeriodWagesReturnVo.class) + }) @ClerkUserLogin @GetMapping("clerk/queryCurrentPeriodWages") public R clerkQueryCurrentPeriodWages() { @@ -101,6 +115,10 @@ public class WxClerkWagesController { * @author admin * @since 2024/5/31 16:20 **/ + @ApiOperation(value = "查询历史工资", notes = "店员查询本人历史工资") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = ClerkHistoricalWagesReturnVo.class, responseContainer = "Page") + }) @ClerkUserLogin @PostMapping("clerk/queryHistoricalWages") public R clerkQueryHistoricalWages() { @@ -124,6 +142,12 @@ public class WxClerkWagesController { * @author admin * @since 2024/5/31 16:20 **/ + @ApiOperation(value = "查询工资详情", notes = "店员查询本人工资详情") + @ApiImplicitParam(name = "id", value = "工资ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = ClerkWagesDetailsReturnVo.class, responseContainer = "List"), + @ApiResponse(code = 500, message = "ID不能为空") + }) @ClerkUserLogin @GetMapping("clerk/queryWagesDetails") public R clerkQueryWagesDetails(@RequestParam("id") String id) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommodityController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommodityController.java index d6f13fa..e4d847c 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommodityController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommodityController.java @@ -5,6 +5,11 @@ import com.starry.admin.modules.clerk.module.entity.PlayClerkCommodityEntity; import com.starry.admin.modules.clerk.service.IPlayClerkCommodityService; import com.starry.admin.modules.weichat.entity.PlayClerkCommodityTreeData; 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.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -20,6 +25,7 @@ import java.util.stream.Collectors; /** * @author admin */ +@Api(tags = "微信商品接口", description = "微信端商品相关接口") @Slf4j @RestController @RequestMapping("/wx/commodity/") @@ -27,6 +33,11 @@ public class WxCommodityController { @Resource private IPlayClerkCommodityService clerkCommodityService; + @ApiOperation(value = "获取商品树", notes = "根据用户ID获取商品树形结构") + @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkCommodityTreeData.class, responseContainer = "List") + }) @GetMapping("/getTree") public R getTree(@RequestParam("userId") String userId) { List commodityEntities = clerkCommodityService.selectByUser(userId); diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommonController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommonController.java index 0e0f963..8d70e95 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommonController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCommonController.java @@ -11,6 +11,12 @@ import com.starry.admin.modules.weichat.utils.WxFileUtils; import com.starry.admin.utils.SecurityUtils; import com.starry.common.result.R; 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 lombok.extern.slf4j.Slf4j; import me.chanjar.weixin.common.error.WxErrorException; import org.springframework.web.bind.annotation.*; @@ -27,6 +33,7 @@ import java.nio.file.Files; * @author admin * @since 2024/4/10 16:18 **/ +@Api(tags = "微信通用接口", description = "微信公共功能相关接口") @Slf4j @RestController @RequestMapping("/wx/common/") @@ -45,22 +52,40 @@ public class WxCommonController { private IShopUiSettingService shopUiSettingService; + @ApiOperation(value = "获取行政区域树", notes = "获取省市区县的树形结构数据") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("area/tree") public R areaTree() { return R.ok(areaDictInfoService.selectTree("2")); } + @ApiOperation(value = "获取店铺UI设置", notes = "获取当前店铺的UI配置信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("setting/info") public R selectShopUiSettingInfo() { return R.ok(shopUiSettingService.selectShopUiSettingInfo()); } + @ApiOperation(value = "上传文件", notes = "上传文件到OSS存储") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功，返回文件访问地址") + }) @PostMapping("file/upload") - public R fileUpload(@RequestParam("file") MultipartFile file) throws IOException { + public R fileUpload(@ApiParam(value = "上传的文件", required = true) @RequestParam("file") MultipartFile file) throws IOException { String fileAddress = ossFileService.upload(file.getInputStream(), SecurityUtils.getTenantId(), file.getOriginalFilename()); return R.ok(fileAddress); } + @ApiOperation(value = "上传音频", notes = "通过微信媒体ID上传音频文件，自动转换为MP3格式") + @ApiImplicitParam(name = "mediaId", value = "微信媒体ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功，返回文件访问地址"), + @ApiResponse(code = 500, message = "上传失败，mediaId为空或文件不存在") + }) @GetMapping("audio/upload") public R audioUpload(@RequestParam("mediaId") String mediaId) throws IOException, WxErrorException { if (StrUtil.isBlankIfStr(mediaId)) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCouponController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCouponController.java index c52f81c..cabacaf 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCouponController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCouponController.java @@ -19,6 +19,12 @@ import com.starry.admin.modules.weichat.entity.WxCouponOrderReturnVo; import com.starry.admin.modules.weichat.entity.WxCouponReceiveReturnVo; 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 lombok.extern.slf4j.Slf4j; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.*; @@ -33,6 +39,7 @@ import java.util.Map; * @author admin * @since 2024/7/4 11:33 **/ +@Api(tags = "微信优惠券接口", description = "微信端优惠券相关接口") @Slf4j @RestController @RequestMapping("/wx/coupon/") @@ -52,6 +59,12 @@ public class WxCouponController { private IPlayCommodityInfoService playCommodityInfoService; + @ApiOperation(value = "领取优惠券", notes = "顾客领取指定ID的优惠券") + @ApiImplicitParam(name = "id", value = "优惠券ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = Map.class), + @ApiResponse(code = 500, message = "请求参数异常,优惠券ID不能为空") + }) @CustomUserLogin @GetMapping("/custom/obtainCoupon") public R queryAll(@RequestParam("id") String id) { @@ -80,6 +93,10 @@ public class WxCouponController { * @author admin * @since 2024/7/8 13:53 **/ + @ApiOperation(value = "查询所有优惠券", notes = "查询所有优惠券并标记用户是否已领取") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = WxCouponReceiveReturnVo.class, responseContainer = "List") + }) @CustomUserLogin @PostMapping("/custom/queryAll") public R queryAll() { @@ -105,9 +122,14 @@ public class WxCouponController { /** * 顾客查询订单可使用优惠券 */ + @ApiOperation(value = "查询订单可用优惠券", notes = "查询当前订单可使用的优惠券列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = WxCouponOrderReturnVo.class, responseContainer = "List"), + @ApiResponse(code = 500, message = "请求参数异常,店员ID不能为空,等级ID不能为空") + }) @CustomUserLogin @PostMapping("/custom/queryByOrder") - public R queryByOrder(@Validated @RequestBody WxCouponOrderQueryVo vo) { + public R queryByOrder(@ApiParam(value = "订单查询条件", required = true) @Validated @RequestBody WxCouponOrderQueryVo vo) { if (vo.getLevelId().isEmpty() && vo.getClerkId().isEmpty()) { throw new CustomException("请求参数异常,店员ID不能为空,等级ID不能为空"); } diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCustomController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCustomController.java index c1ddaef..c747f62 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCustomController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxCustomController.java @@ -49,6 +49,12 @@ import com.starry.common.result.R; import com.starry.common.utils.ConvertUtil; import com.starry.common.utils.IdUtils; import com.starry.common.utils.StringUtils; +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 lombok.extern.slf4j.Slf4j; import org.springframework.beans.BeanUtils; import org.springframework.validation.annotation.Validated; @@ -63,6 +69,7 @@ import java.util.Objects; /** * @author admin */ +@Api(tags = "微信顾客接口", description = "微信端顾客相关接口") @Slf4j @RestController @RequestMapping("/wx/custom/") @@ -126,6 +133,11 @@ public class WxCustomController { * @param id 店员ID * @return 店员详细信息 */ + @ApiOperation(value = "查询店员详细信息", notes = "根据店员ID查询店员的详细信息") + @ApiImplicitParam(name = "id", value = "店员ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkUserInfoResultVo.class) + }) @GetMapping("/queryClerkDetailedById") public R queryClerkDetailedById(@RequestParam("id") String id) { PlayClerkUserInfoEntity entity = clerkUserInfoService.selectById(id); @@ -144,6 +156,10 @@ public class WxCustomController { /** * 顾客本人刷新头像 */ + @ApiOperation(value = "刷新顾客头像", notes = "刷新当前登录顾客的头像信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @CustomUserLogin @GetMapping("/refreshAvatar") public R refreshAvatar() { @@ -153,6 +169,10 @@ public class WxCustomController { /** * 根据顾客ID查询当前顾客详细信息 */ + @ApiOperation(value = "查询顾客详细信息", notes = "查询当前登录顾客的详细信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomUserReturnDetailVo.class) + }) @CustomUserLogin @GetMapping("/queryById") public R queryById() { @@ -169,9 +189,13 @@ public class WxCustomController { /** * 顾客本人修改隐藏等级状态 */ + @ApiOperation(value = "修改隐藏等级状态", notes = "顾客修改自己的隐藏等级状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @CustomUserLogin @PostMapping("/updateHideLevelState") - public R updateHideLevelState(@Validated @RequestBody PlayCustomHideLevelStateEditVo vo) { + public R updateHideLevelState(@ApiParam(value = "隐藏等级状态信息", required = true) @Validated @RequestBody PlayCustomHideLevelStateEditVo vo) { vo.setId(ThreadLocalRequestDetail.getCustomUserInfo().getId()); PlayCustomUserInfoEntity entity = new PlayCustomUserInfoEntity(); BeanUtils.copyProperties(vo, entity); @@ -182,9 +206,13 @@ public class WxCustomController { /** * 顾客本人修改隐藏排名状态 */ + @ApiOperation(value = "修改隐藏排名状态", notes = "顾客修改自己的隐藏排名状态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @CustomUserLogin @PostMapping("/updateHideRankingState") - public R updateHideRankingState(@Validated @RequestBody PlayCustomHideRankingStateEditVo vo) { + public R updateHideRankingState(@ApiParam(value = "隐藏排名状态信息", required = true) @Validated @RequestBody PlayCustomHideRankingStateEditVo vo) { vo.setId(ThreadLocalRequestDetail.getCustomUserInfo().getId()); PlayCustomUserInfoEntity entity = new PlayCustomUserInfoEntity(); BeanUtils.copyProperties(vo, entity); @@ -196,9 +224,14 @@ public class WxCustomController { /** * 打赏店员-打赏余额 */ + @ApiOperation(value = "打赏店员", notes = "使用余额打赏店员") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 998, message = "余额不足") + }) @CustomUserLogin @PostMapping("/order/reward") - public R rewardToOrder(@Validated @RequestBody PlayOrderInfoRewardAdd vo) { + public R rewardToOrder(@ApiParam(value = "打赏信息", required = true) @Validated @RequestBody PlayOrderInfoRewardAdd vo) { MoneyUtils.verificationTypeIsNormal(vo.getMoney()); String userId = ThreadLocalRequestDetail.getCustomUserInfo().getId(); PlayCustomUserInfoEntity customUserInfo = customUserInfoService.selectById(userId); @@ -217,9 +250,14 @@ public class WxCustomController { /** * 顾客下单-赠送礼物 **/ + @ApiOperation(value = "赠送礼物", notes = "顾客向店员赠送礼物") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 998, message = "余额不足") + }) @CustomUserLogin @PostMapping("/order/gift") - public R giftToOdder(@Validated @RequestBody PlayOrderInfoGiftAdd vo) { + public R giftToOdder(@ApiParam(value = "礼物信息", required = true) @Validated @RequestBody PlayOrderInfoGiftAdd vo) { String userId = ThreadLocalRequestDetail.getCustomUserInfo().getId(); PlayGiftInfoEntity giftInfo = giftInfoService.selectPlayGiftInfoById(vo.getGiftId()); PlayCustomUserInfoEntity customUserInfo = customUserInfoService.selectById(userId); @@ -271,9 +309,15 @@ public class WxCustomController { * @author admin * @since 2024/5/8 16:31 **/ + @ApiOperation(value = "商品下单", notes = "顾客购买店员服务商品") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 998, message = "余额不足"), + @ApiResponse(code = 500, message = "请求参数异常") + }) @CustomUserLogin @PostMapping("/order/commodity") - public R commodityToOrdder(@Validated @RequestBody PlayOrderInfoCommodityAdd vo) { + public R commodityToOrdder(@ApiParam(value = "商品订单信息", required = true) @Validated @RequestBody PlayOrderInfoCommodityAdd vo) { String customId = ThreadLocalRequestDetail.getCustomUserInfo().getId(); PlayClerkUserInfoEntity clerkUserInfo = clerkUserInfoService.selectById(vo.getClerkId()); diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxGiftController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxGiftController.java index 8785fca..5ee507d 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxGiftController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxGiftController.java @@ -11,6 +11,11 @@ import com.starry.admin.modules.weichat.entity.PlayGiftInfoDto; import com.starry.admin.modules.weichat.entity.gift.PlayClerkGiftReturnVo; 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.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -23,6 +28,7 @@ import java.util.List; /** * @author admin */ +@Api(tags = "微信礼物接口", description = "微信端礼物相关接口") @Slf4j @RestController @RequestMapping("/wx/gift/") @@ -35,6 +41,10 @@ public class WxGiftController { * * @return 礼物列表 */ + @ApiOperation(value = "查询所有礼物", notes = "查询系统中所有礼物列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayGiftInfoDto.class, responseContainer = "List") + }) @GetMapping("/listByAll") public R customListByAll() { return R.ok(ConvertUtil.entityToVoList(giftInfoService.listByAll(),PlayGiftInfoDto.class)); @@ -47,6 +57,12 @@ public class WxGiftController { * @param obtained 店员获得礼物状态,[0:未获得,1:已获得] * @return 礼物列表 */ + @ApiOperation(value = "店员查询礼物", notes = "根据获得状态查询店员礼物列表") + @ApiImplicitParam(name = "obtained", value = "获得状态[0:未获得,1:已获得]", required = true, dataType = "String", paramType = "query", allowableValues = "0,1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkGiftReturnVo.class, responseContainer = "List"), + @ApiResponse(code = 500, message = "obtained参数异常") + }) @ClerkUserLogin @GetMapping("/clerk/listByAll") public R clerkListByAll(@RequestParam("obtained") String obtained) { @@ -67,6 +83,12 @@ public class WxGiftController { * @param vo 顾客获得礼物查询对象 * @return 礼物列表 */ + @ApiOperation(value = "顾客查询礼物", notes = "根据获得状态查询顾客礼物列表") + @ApiImplicitParam(name = "obtained", value = "获得状态[0:未获得,1:已获得]", required = true, dataType = "String", paramType = "query", allowableValues = "0,1") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayClerkGiftReturnVo.class, responseContainer = "List"), + @ApiResponse(code = 500, message = "obtained参数异常") + }) @CustomUserLogin @GetMapping("/custom/listByAll") public R customListByAll(@RequestParam("obtained") String obtained) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxLevelController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxLevelController.java index 1ab2805..778dce3 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxLevelController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxLevelController.java @@ -6,6 +6,10 @@ import com.starry.admin.modules.custom.module.entity.PlayCustomLevelInfoEntity; import com.starry.admin.modules.custom.service.IPlayCustomLevelInfoService; import com.starry.admin.modules.weichat.entity.vo.PlayCustomLevelInfoReturnVo; import com.starry.common.result.R; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.BeanUtils; import org.springframework.web.bind.annotation.GetMapping; @@ -19,6 +23,7 @@ import java.util.List; /** * @author admin */ +@Api(tags = "微信等级接口", description = "微信端用户等级相关接口") @Slf4j @RestController @RequestMapping("/wx/level/") @@ -31,6 +36,10 @@ public class WxLevelController { /** * 顾客查询登记列表 */ + @ApiOperation(value = "查询等级列表", notes = "查询所有顾客等级列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayCustomLevelInfoReturnVo.class, responseContainer = "List") + }) @CustomUserLogin @GetMapping("/custom/queryAll") public R queryById() { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOauthController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOauthController.java index 33c9bcb..fbb42c6 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOauthController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOauthController.java @@ -18,6 +18,12 @@ import com.starry.admin.modules.weichat.service.WxOauthService; import com.starry.admin.modules.weichat.service.WxTokenService; import com.starry.common.redis.RedisCache; 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 lombok.extern.slf4j.Slf4j; import me.chanjar.weixin.common.bean.WxJsapiSignature; import me.chanjar.weixin.common.error.WxErrorException; @@ -35,6 +41,7 @@ import static com.starry.common.constant.Constants.*; * @author admin * @since 2019-03-25 15:39:39 */ +@Api(tags = "微信授权接口", description = "微信端用户授权相关接口") @Slf4j @RestController @RequestMapping("/wx/oauth2") @@ -55,8 +62,12 @@ public class WxOauthController { private RedisCache redisCache; + @ApiOperation(value = "获取配置地址", notes = "获取微信JSAPI配置签名") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = WxJsapiSignature.class) + }) @PostMapping("/getConfigAddress") - public R getConfigAddress(@RequestBody WxUserQueryAddressVo vo) throws WxErrorException { + public R getConfigAddress(@ApiParam(value = "地址查询信息", required = true) @RequestBody WxUserQueryAddressVo vo) throws WxErrorException { // 默认回调地址 String defaultAddress = "http://july.hucs.top/api/wx/oauth2/clerkLoginCallback"; if (!StrUtil.isBlankIfStr(vo.getUrl())) { @@ -66,8 +77,12 @@ public class WxOauthController { return R.ok(wxJsapiSignature); } + @ApiOperation(value = "获取店员登录地址", notes = "获取微信店员授权登录地址") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class) + }) @PostMapping("/getClerkLoginAddress") - public R getClerkLoginAddress(@RequestBody WxUserQueryAddressVo vo) { + public R getClerkLoginAddress(@ApiParam(value = "地址查询信息", required = true) @RequestBody WxUserQueryAddressVo vo) { // 默认回调地址 String defaultAddress = "http://july.hucs.top/api/wx/oauth2/clerkLoginCallback"; if (!StrUtil.isBlankIfStr(vo.getUrl())) { @@ -78,13 +93,21 @@ public class WxOauthController { } + @ApiOperation(value = "店员登录回调", notes = "微信店员授权登录回调处理") + @ApiImplicitParam(name = "code", value = "授权码", required = true, dataType = "String", paramType = "query") @GetMapping("/clerkLoginCallback") public void clerkLoginCallback(@RequestParam("code") String code) { } + @ApiOperation(value = "店员登录", notes = "微信店员授权登录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = JSONObject.class), + @ApiResponse(code = 401, message = "登录失败"), + @ApiResponse(code = 500, message = "用户不存在") + }) @PostMapping("/clerk/login") - public R clerkLogin(@Validated @RequestBody WxUserLoginVo vo) { + public R clerkLogin(@ApiParam(value = "登录信息", required = true) @Validated @RequestBody WxUserLoginVo vo) { try { String userId = wxOauthService.clerkUserLogin(vo.getCode()); PlayClerkUserInfoEntity entity = clerkUserInfoService.selectById(userId); @@ -108,8 +131,14 @@ public class WxOauthController { } } + @ApiOperation(value = "店员开发登录", notes = "微信店员开发环境登录（固定用户）") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = JSONObject.class), + @ApiResponse(code = 401, message = "登录失败"), + @ApiResponse(code = 500, message = "用户不存在") + }) @PostMapping("/clerk/login/dev") - public R clerkLoginDev(@Validated @RequestBody WxUserLoginVo vo) { + public R clerkLoginDev(@ApiParam(value = "登录信息", required = true) @Validated @RequestBody WxUserLoginVo vo) { try { String userId = "a4471ef596a1"; PlayClerkUserInfoEntity entity = clerkUserInfoService.selectById(userId); @@ -133,8 +162,13 @@ public class WxOauthController { } } + @ApiOperation(value = "店员ID登录", notes = "根据店员ID直接登录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = JSONObject.class), + @ApiResponse(code = 500, message = "用户不存在") + }) @PostMapping("/clerk/loginById") - public R loginById(@Validated @RequestBody WxUserLoginVo vo) { + public R loginById(@ApiParam(value = "登录信息", required = true) @Validated @RequestBody WxUserLoginVo vo) { PlayClerkUserInfoEntity entity = clerkUserInfoService.selectById(vo.getCode()); if (entity == null) { throw new CustomException("用户不存在"); @@ -151,6 +185,10 @@ public class WxOauthController { return R.ok(jsonObject); } + @ApiOperation(value = "店员登出", notes = "店员退出登录") + @ApiResponses({ + @ApiResponse(code = 200, message = "登出成功") + }) @ClerkUserLogin @GetMapping("/clerk/logout") public R clerkLogout() { @@ -159,8 +197,12 @@ public class WxOauthController { } + @ApiOperation(value = "获取顾客登录地址", notes = "获取微信顾客授权登录地址") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = String.class) + }) @PostMapping("/getCustomLoginAddress") - public R getCustomLoginAddress(@RequestBody WxUserQueryAddressVo vo) { + public R getCustomLoginAddress(@ApiParam(value = "地址查询信息", required = true) @RequestBody WxUserQueryAddressVo vo) { // 默认回调地址 String defaultAddress = "http://july.hucs.top/api/wx/oauth2/customLoginCallback"; if (!StrUtil.isBlankIfStr(vo.getUrl())) { @@ -170,14 +212,22 @@ public class WxOauthController { return R.ok(url); } + @ApiOperation(value = "顾客登录回调", notes = "微信顾客授权登录回调处理") + @ApiImplicitParam(name = "code", value = "授权码", required = true, dataType = "String", paramType = "query") @GetMapping("/customLoginCallback") public void customLoginCallback(@RequestParam("code") String code) { } + @ApiOperation(value = "顾客登录", notes = "微信顾客授权登录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = JSONObject.class), + @ApiResponse(code = 401, message = "登录失败"), + @ApiResponse(code = 500, message = "用户不存在") + }) @PostMapping("/custom/login") - public R customLogin(@Validated @RequestBody WxUserLoginVo vo) { + public R customLogin(@ApiParam(value = "登录信息", required = true) @Validated @RequestBody WxUserLoginVo vo) { log.info("顾客登录接口调用，code = {}", vo.getCode()); try { String userId = wxOauthService.customUserLogin(vo.getCode()); @@ -201,8 +251,13 @@ public class WxOauthController { } } + @ApiOperation(value = "顾客ID登录", notes = "根据顾客ID直接登录") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = JSONObject.class), + @ApiResponse(code = 500, message = "用户不存在") + }) @PostMapping("/custom/loginById") - public R loginById1(@Validated @RequestBody WxUserLoginVo vo) { + public R loginById1(@ApiParam(value = "登录信息", required = true) @Validated @RequestBody WxUserLoginVo vo) { PlayCustomUserInfoEntity entity = customUserInfoService.selectById(vo.getCode()); if (entity == null) { throw new CustomException("用户不存在"); @@ -220,6 +275,10 @@ public class WxOauthController { } + @ApiOperation(value = "顾客登出", notes = "顾客退出登录") + @ApiResponses({ + @ApiResponse(code = 200, message = "登出成功") + }) @GetMapping("/custom/logout") @CustomUserLogin public R customLogout() { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOrderInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOrderInfoController.java index 5bb18ff..5befacf 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOrderInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxOrderInfoController.java @@ -18,6 +18,12 @@ import com.starry.admin.modules.weichat.entity.order.PlayOrderInfoContinueQueryV import com.starry.admin.modules.weichat.entity.order.PlayOrderInfoRandomQueryVo; import com.starry.admin.modules.weichat.entity.order.PlayRewardOrderQueryVo; 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 lombok.extern.slf4j.Slf4j; import org.springframework.beans.BeanUtils; import org.springframework.validation.annotation.Validated; @@ -32,6 +38,7 @@ import java.time.LocalDateTime; * @author admin * @since 2024/5/25 下午2:45 **/ +@Api(tags = "微信订单接口", description = "微信端订单相关接口") @Slf4j @RestController @RequestMapping("/wx/order") @@ -49,9 +56,15 @@ public class WxOrderInfoController { * * @param vo 续单申请提交对象 */ + @ApiOperation(value = "店员申请续单", notes = "店员为当前订单发起续单申请") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "非本人订单;无法续单"), + @ApiResponse(code = 500, message = "同一场订单只能续单一次") + }) @ClerkUserLogin @PostMapping("/clerk/continue") - public R continueToOrdder(@Validated @RequestBody PlayOrderInfoContinueAdd vo) { + public R continueToOrdder(@ApiParam(value = "续单信息", required = true) @Validated @RequestBody PlayOrderInfoContinueAdd vo) { PlayOrderInfoEntity entity = playOrderInfoService.selectOrderInfoById(vo.getOrderId()); if (!entity.getAcceptBy().equals(ThreadLocalRequestDetail.getClerkUserInfo().getId())) { throw new CustomException("非本人订单;无法续单"); @@ -85,9 +98,13 @@ public class WxOrderInfoController { * @param vo 随机单列表查询对象 * @return 订单列表 */ + @ApiOperation(value = "查询随机单列表", notes = "店员查询可接的随机订单列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @ClerkUserLogin @PostMapping("/clerk/selectRandomOrderByPage") - public R selectUnacceptedOrderByPage(@Validated @RequestBody PlayOrderInfoRandomQueryVo vo) { + public R selectUnacceptedOrderByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderInfoRandomQueryVo vo) { return R.ok(playOrderInfoService.selectRandomOrderByPage(vo,ThreadLocalRequestDetail.getClerkUserInfo().getId())); } @@ -97,6 +114,12 @@ public class WxOrderInfoController { * @param id 订单ID * @return 订单列表 */ + @ApiOperation(value = "查询随机单详情", notes = "店员查询随机订单的详细信息") + @ApiImplicitParam(name = "id", value = "订单ID", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderDetailsReturnVo.class), + @ApiResponse(code = 500, message = "订单不存在") + }) @ClerkUserLogin @GetMapping("/clerk/selectRandomOrderById") public R selectUnacceptedOrderByPage(@RequestParam("id") String id) { @@ -113,9 +136,12 @@ public class WxOrderInfoController { * @param vo 打赏动态查询列表 * @return 打赏动态列表 */ - + @ApiOperation(value = "店员查询打赏动态", notes = "店员查询打赏订单动态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @PostMapping("/clerk/selectRewardByPage") - public R clerkSelectRewardByPage(@Validated @RequestBody PlayRewardOrderQueryVo vo) { + public R clerkSelectRewardByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayRewardOrderQueryVo vo) { return R.ok(playOrderInfoService.selectRewardByPage(vo)); } @@ -124,7 +150,10 @@ public class WxOrderInfoController { * * @return 打赏动态列表 */ - + @ApiOperation(value = "顾客查询打赏动态", notes = "顾客查询最新打赏订单动态") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("/custom/selectRewardByPage") public R customSelectReward() { PlayRewardOrderQueryVo vo = new PlayRewardOrderQueryVo(); @@ -138,9 +167,13 @@ public class WxOrderInfoController { * @param vo PlayOrderInfoContinueQueryVo * @return 续单历史 */ + @ApiOperation(value = "查询续单列表", notes = "顾客分页查询续单申请列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderContinueReturnVo.class, responseContainer = "Page") + }) @CustomUserLogin @PostMapping("/custom/continueListByPage") - public R continueListByPage(@Validated @RequestBody PlayOrderInfoContinueQueryVo vo) { + public R continueListByPage(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayOrderInfoContinueQueryVo vo) { PlayOrderContinueQueryVo queryVo = new PlayOrderContinueQueryVo(); BeanUtils.copyProperties(vo, queryVo); queryVo.setCustomId(ThreadLocalRequestDetail.getCustomUserInfo().getId()); @@ -152,9 +185,14 @@ public class WxOrderInfoController { /** * 审批续单申申请 */ + @ApiOperation(value = "审批续单申请", notes = "顾客审批店员发起的续单申请") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "续单已处理") + }) @CustomUserLogin @PostMapping("/custom/updateReviewState") - public R updateReviewState(@Validated @RequestBody PlayOrderReviewStateEditVo vo) { + public R updateReviewState(@ApiParam(value = "审批信息", required = true) @Validated @RequestBody PlayOrderReviewStateEditVo vo) { PlayOrderContinueInfoEntity entity = playOrderContinueInfoService.selectPlayOrderContinueInfoById(vo.getId()); if (!"0".equals(entity.getReviewedState())) { throw new CustomException("续单已处理"); diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPersonnelGroupInfoController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPersonnelGroupInfoController.java index 27c8679..f8b7fb7 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPersonnelGroupInfoController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPersonnelGroupInfoController.java @@ -6,6 +6,11 @@ import com.starry.admin.modules.personnel.service.IPlayPersonnelGroupInfoService import com.starry.admin.modules.weichat.entity.PlayGroupWagesQueryVo; import com.starry.admin.modules.weichat.entity.PlayGroupWagesReturnVo; 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 lombok.extern.slf4j.Slf4j; import org.springframework.validation.annotation.Validated; import org.springframework.web.bind.annotation.PostMapping; @@ -23,6 +28,7 @@ import java.util.List; * @author admin * @since 2024/7/6 下午3:46 **/ +@Api(tags = "微信分组管理", description = "微信端店员分组相关接口") @Slf4j @RestController @RequestMapping("/wx/group") @@ -36,9 +42,13 @@ public class WxPersonnelGroupInfoController { /** * 查询组长公工资 */ + @ApiOperation(value = "查询分组工资", notes = "获取所有店员分组的工资信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayGroupWagesReturnVo.class, responseContainer = "List") + }) @ClerkUserLogin @PostMapping("/wages/listAll") - public R listGroupWagesAll(@Validated @RequestBody PlayGroupWagesQueryVo vo) { + public R listGroupWagesAll(@ApiParam(value = "查询条件", required = true) @Validated @RequestBody PlayGroupWagesQueryVo vo) { List list = playClerkGroupInfoService.selectAll(); List data = new ArrayList<>(); for (PlayPersonnelGroupInfoEntity entity : list) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayController.java index 5c49922..5a72cd7 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayController.java @@ -29,6 +29,11 @@ import com.starry.admin.modules.weichat.service.WxCustomMpService; import com.starry.admin.utils.SecurityUtils; import com.starry.common.result.R; import com.starry.common.utils.StringUtils; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiImplicitParam; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.dom4j.Document; import org.dom4j.DocumentHelper; @@ -51,6 +56,7 @@ import java.util.Objects; /** * @author admin */ +@Api(tags = "微信支付接口", description = "微信端支付相关接口") @Slf4j @RestController @RequestMapping("/wx/pay/") @@ -75,6 +81,10 @@ public class WxPlayController { * @author admin * @since 2024/5/8 11:25 **/ + @ApiOperation(value = "微信支付回调", notes = "微信支付后的回调接口") + @ApiResponses({ + @ApiResponse(code = 200, message = "成功") + }) @RequestMapping("/jsCallback") public String wxPayNotify(HttpServletRequest request) { try (InputStream inStream = request.getInputStream(); ByteArrayOutputStream outSteam = new ByteArrayOutputStream()) { @@ -130,15 +140,24 @@ public class WxPlayController { } } + @ApiOperation(value = "测试消息推送", notes = "测试充值消息推送功能") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("/test") public R test() { - PlayOrderInfoEntity orderInfo = playOrderInfoService.getById("0e3e7d7ec69a"); mpService.sendBalanceMessage(orderInfo); return R.ok(true); } + @ApiOperation(value = "获取支付金额", notes = "根据充值金额获取实际支付金额") + @ApiImplicitParam(name = "money", value = "充值金额", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "请求参数错误,money不能为空") + }) @CustomUserLogin @GetMapping("/custom/getCustomPaymentAmount") public R getCustomPaymentAmount(@RequestParam("money") String money) { @@ -149,6 +168,14 @@ public class WxPlayController { return R.ok(paymentAmount); } + @ApiOperation(value = "创建充值订单", notes = "创建微信支付充值订单") + @ApiImplicitParam(name = "money", value = "充值金额", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功"), + @ApiResponse(code = 500, message = "请求参数错误,money不能为空"), + @ApiResponse(code = 500, message = "充值金额不能小于10元"), + @ApiResponse(code = 500, message = "系统错误,租户ID获取失败") + }) @CustomUserLogin @GetMapping("/custom/createOrder") public R createOrder(@RequestParam("money") String money) { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayOrderRankingController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayOrderRankingController.java index 27519cc..0afa6ea 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayOrderRankingController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxPlayOrderRankingController.java @@ -6,6 +6,10 @@ import com.starry.admin.modules.clerk.service.IPlayClerkRankingInfoService; import com.starry.admin.modules.weichat.entity.order.PlayOrderHistoryRankingReturnVo; import com.starry.admin.modules.weichat.entity.order.PlayOrderRankingReturnVo; import com.starry.common.result.R; +import io.swagger.annotations.Api; +import io.swagger.annotations.ApiOperation; +import io.swagger.annotations.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -18,6 +22,7 @@ import java.util.List; * @author admin * @since 2024/5/25 下午10:25 **/ +@Api(tags = "微信订单排行接口", description = "微信端订单排行相关接口") @Slf4j @RestController @RequestMapping("/wx/orderRanking") @@ -31,6 +36,10 @@ public class WxPlayOrderRankingController { /** * 查询当前排行 */ + @ApiOperation(value = "查询当前排行", notes = "查询店员当前排行榜信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderRankingReturnVo.class) + }) @ClerkUserLogin @GetMapping("/clerk/selectCurrentRanking") public R selectCurrentRanking() { @@ -42,6 +51,10 @@ public class WxPlayOrderRankingController { /** * 查询历史排行 */ + @ApiOperation(value = "查询历史排行", notes = "查询店员历史排行榜信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayOrderHistoryRankingReturnVo.class, responseContainer = "List") + }) @ClerkUserLogin @GetMapping("/clerk/selectHistoryRanking") public R selectHistoryRanking() { diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxShopController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxShopController.java index 670d2e0..bc512bd 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxShopController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxShopController.java @@ -9,6 +9,11 @@ import com.starry.admin.modules.weichat.entity.PlayShopReadArticleVo; import com.starry.admin.modules.weichat.entity.shop.ShopHomeCarouseInfoReturnVo; import com.starry.common.result.R; import com.starry.common.utils.ConvertUtil; +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 lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestBody; @@ -24,6 +29,7 @@ import java.util.List; * @author admin * @since 2024/5/20 下午11:19 **/ +@Api(tags = "微信店铺接口", description = "微信端店铺相关接口") @Slf4j @RestController @RequestMapping("/wx/shop") @@ -39,6 +45,10 @@ public class WxShopController { /** * 获取首页轮播图 */ + @ApiOperation(value = "获取首页轮播图", notes = "获取店铺首页轮播图信息") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = ShopHomeCarouseInfoReturnVo.class, responseContainer = "List") + }) @GetMapping(value = "custom/getShopHomeCarouseInfo") public R getShopHomeCarouseInfo() { List entities = playShopCarouselInfoService.selectHomeCarouselInfo(); @@ -49,6 +59,10 @@ public class WxShopController { /** * 获取店铺文章列表 */ + @ApiOperation(value = "获取文章列表", notes = "获取店铺所有文章列表") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功", response = PlayShopArticleInfoEntity.class, responseContainer = "List") + }) @ClerkUserLogin @GetMapping(value = "clerk/getArticleList") public R getArticleList() { @@ -59,9 +73,13 @@ public class WxShopController { /** * 阅读店铺文章 */ + @ApiOperation(value = "阅读文章", notes = "阅读店铺文章并增加访问次数") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @ClerkUserLogin @GetMapping(value = "clerk/readShopArticleInfo") - public R readShopArticleInfo(@RequestBody PlayShopReadArticleVo vo) { + public R readShopArticleInfo(@ApiParam(value = "文章参数", required = true) @RequestBody PlayShopReadArticleVo vo) { PlayShopArticleInfoEntity entity = playShopArticleInfoService.selectById(vo.getId()); entity.setVisitsNumber(entity.getVisitsNumber() + 1); playShopArticleInfoService.update(entity); diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxSmsController.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxSmsController.java index 781f0c5..3b77822 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxSmsController.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/controller/WxSmsController.java @@ -2,6 +2,11 @@ package com.starry.admin.modules.weichat.controller; import com.starry.admin.utils.SmsUtils; 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.ApiResponse; +import io.swagger.annotations.ApiResponses; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; @@ -16,6 +21,7 @@ import javax.annotation.Resource; * @author admin * @since 2024/5/20 下午11:19 **/ +@Api(tags = "微信短信接口", description = "微信端短信发送相关接口") @Slf4j @RestController @RequestMapping("/wx/sms") @@ -23,6 +29,11 @@ public class WxSmsController { @Resource private SmsUtils smsUtils; + @ApiOperation(value = "发送短信", notes = "向指定手机号发送短信验证码") + @ApiImplicitParam(name = "phone", value = "手机号码", required = true, dataType = "String", paramType = "query") + @ApiResponses({ + @ApiResponse(code = 200, message = "操作成功") + }) @GetMapping("/send") public R sendSms(@RequestParam("phone") String phone) { smsUtils.sendSmsApi(phone); diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoQueryVo.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoQueryVo.java index 7612f65..4f63420 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoQueryVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoQueryVo.java @@ -1,6 +1,8 @@ package com.starry.admin.modules.weichat.entity.clerk; import com.starry.common.domain.BasePageEntity; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.EqualsAndHashCode; @@ -12,56 +14,67 @@ import lombok.EqualsAndHashCode; */ @Data @EqualsAndHashCode(callSuper = false) +@ApiModel(value = "店员查询参数", description = "分页查询店员的条件参数对象") public class PlayClerkUserInfoQueryVo extends BasePageEntity { /** * 店员昵称 **/ + @ApiModelProperty(value = "店员昵称", example = "张三", notes = "支持模糊查询") private String nickname; /** * 店员等级 */ + @ApiModelProperty(value = "店员等级ID") private String levelId; /** * 店员类型 */ + @ApiModelProperty(value = "店员类型ID") private String typeId; /** * 性别[0:未知;1:男;2:女] */ + @ApiModelProperty(value = "性别", example = "1", notes = "0:未知;1:男;2:女") private String sex; /** * 所在省份 */ + @ApiModelProperty(value = "所在省份", example = "广东省") private String province; /** * 上架状态【1：上架，0：下架】 */ + @ApiModelProperty(value = "上架状态", example = "1", notes = "1：上架，0：下架") private String listingState; /** * 是否推荐状态（1：已推荐，0：未推荐） */ + @ApiModelProperty(value = "是否推荐", example = "1", notes = "1：已推荐，0：未推荐") private String recommendationState; /** * 员工状态【1：是陪聊，0：不是陪聊】 */ + @ApiModelProperty(value = "员工状态", example = "1", notes = "1：是陪聊，0：不是陪聊", required = true) private String clerkState = "1"; /** * 在职状态（1：在职，0：离职） */ + @ApiModelProperty(value = "在职状态", example = "1", notes = "1：在职，0：离职", required = true) private String onboardingState = "1"; /** * 手机号码 */ + @ApiModelProperty(value = "手机号码", example = "13800138000") private String phone; diff --git a/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoResultVo.java b/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoResultVo.java index dfc5959..c25dc59 100644 --- a/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoResultVo.java +++ b/play-admin/src/main/java/com/starry/admin/modules/weichat/entity/clerk/PlayClerkUserInfoResultVo.java @@ -1,5 +1,7 @@ package com.starry.admin.modules.weichat.entity.clerk; +import io.swagger.annotations.ApiModel; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.util.ArrayList; @@ -9,127 +11,151 @@ import java.util.List; * @author admin */ @Data +@ApiModel(value = "店员信息返回对象", description = "查询店员列表的返回结果对象") public class PlayClerkUserInfoResultVo { /** * UUID */ + @ApiModelProperty(value = "店员ID", notes = "唯一标识") private String id; /** * 店员昵称 */ + @ApiModelProperty(value = "店员昵称") private String nickname; /** * 店员等级 */ + @ApiModelProperty(value = "店员等级ID") private String levelId; /** * 店员等级 */ + @ApiModelProperty(value = "店员等级名称") private String levelName; /** * 性别[0:未知;1:男;2:女] */ + @ApiModelProperty(value = "性别", notes = "0:未知;1:男;2:女") private String sex; /** * 头像 */ + @ApiModelProperty(value = "头像", notes = "头像图片URL") private String avatar; /** * 音频 */ + @ApiModelProperty(value = "音频", notes = "音频文件URL") private String audio; /** * 星座 */ + @ApiModelProperty(value = "星座", example = "天蝎座") private String constellation; /** * 标签 */ + @ApiModelProperty(value = "标签列表", notes = "店员个人标签") private List label = new ArrayList<>(); /** * 相册 */ + @ApiModelProperty(value = "相册列表", notes = "店员相册图片URL列表") private List album = new ArrayList<>(); /** * 个性签名 */ + @ApiModelProperty(value = "个性签名") private String signature; /** * 年龄 */ + @ApiModelProperty(value = "年龄", example = "25") private Integer age; /** * 所在省份 */ + @ApiModelProperty(value = "所在省份", example = "广东省") private String province; /** * 所在城市 */ + @ApiModelProperty(value = "所在城市", example = "深圳市") private String city; /** * 关注（0：未关注，1:已关注） */ + @ApiModelProperty(value = "关注状态", notes = "0：未关注，1:已关注", example = "0") private String followState = "0"; /** * 在线状态【1：在线，0：离线】 */ + @ApiModelProperty(value = "在线状态", notes = "1：在线，0：离线") private String onlineState; /** * 上架状态【1：上架，0：下架】 */ + @ApiModelProperty(value = "上架状态", notes = "1：上架，0：下架") private String listingState; /** * 实名状态【1：已实名，0：未实名】 */ + @ApiModelProperty(value = "实名状态", notes = "1：已实名，0：未实名") private String realState; /** * 是否必须实名【1：必须实名，0：非必须实名,2:跟随店铺设置】 */ + @ApiModelProperty(value = "是否必须实名", notes = "1：必须实名，0：非必须实名,2:跟随店铺设置") private String mandatoryRealState; /** * 随机接单状态【1：允许，0：禁止】 */ + @ApiModelProperty(value = "随机接单状态", notes = "1：允许，0：禁止") private String randomOrderState; /** * 服务项目 */ + @ApiModelProperty(value = "服务项目列表", notes = "店员提供的服务项目") private List commodity; /** * 地址 */ + @ApiModelProperty(value = "地址", notes = "店员所在详细地址") private String address; /** * 最低消费 */ + @ApiModelProperty(value = "最低消费", notes = "店员服务的最低消费", example = "最低1船票") private String latestConsumption = "最低1船票"; diff --git a/play-common/src/main/java/com/starry/common/domain/BasePageEntity.java b/play-common/src/main/java/com/starry/common/domain/BasePageEntity.java index 6cf720c..079b2f5 100644 --- a/play-common/src/main/java/com/starry/common/domain/BasePageEntity.java +++ b/play-common/src/main/java/com/starry/common/domain/BasePageEntity.java @@ -2,6 +2,7 @@ package com.starry.common.domain; import com.baomidou.mybatisplus.annotation.FieldFill; import com.baomidou.mybatisplus.annotation.TableField; +import io.swagger.annotations.ApiModelProperty; import lombok.Data; import lombok.experimental.Accessors; import org.springframework.format.annotation.DateTimeFormat; @@ -18,38 +19,48 @@ import java.util.Date; @Accessors(chain = true) public class BasePageEntity implements Serializable { + @ApiModelProperty(value = "当前页码", example = "1", notes = "默认为1") private int currentPage = 1; + @ApiModelProperty(value = "每页记录数", example = "10", notes = "默认为10") private int pageSize = 10; + @ApiModelProperty(value = "页码", example = "1", notes = "与currentPage相同，默认为1") private int pageNum = 1; @TableField(fill = FieldFill.INSERT) + @ApiModelProperty(value = "是否已删除", example = "false", hidden = true) private Boolean deleted = Boolean.FALSE; @TableField(fill = FieldFill.INSERT) + @ApiModelProperty(value = "创建人", hidden = true) private String createdBy; @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") @TableField(fill = FieldFill.INSERT) + @ApiModelProperty(value = "创建时间", hidden = true) private Date createdTime; @TableField(fill = FieldFill.UPDATE) + @ApiModelProperty(value = "更新时间", hidden = true) private Date updatedTime; @TableField(fill = FieldFill.UPDATE) + @ApiModelProperty(value = "更新人", hidden = true) private String updatedBy; /** * 开始日期 */ @TableField(exist = false) + @ApiModelProperty(value = "开始日期", example = "2024-01-01 00:00:00", notes = "格式：yyyy-MM-dd HH:mm:ss") private String beginTime; /** * 结束日期 */ @TableField(exist = false) + @ApiModelProperty(value = "结束日期", example = "2024-12-31 23:59:59", notes = "格式：yyyy-MM-dd HH:mm:ss") private String endTime; }