From 05438d025aeac2b8487f6a931cd59fd4a3573e93 Mon Sep 17 00:00:00 2001 From: pbvfus8to <480171784@qq.com> Date: Wed, 18 Dec 2024 10:46:47 +0800 Subject: [PATCH] Update NoticeController.java --- .../shop/api/controller/NoticeController.java | 39 ++++++++++++++----- 1 file changed, 30 insertions(+), 9 deletions(-) diff --git a/yami-shop-api/src/main/java/com/yami/shop/api/controller/NoticeController.java b/yami-shop-api/src/main/java/com/yami/shop/api/controller/NoticeController.java index 918ee35..d948c8d 100644 --- a/yami-shop-api/src/main/java/com/yami/shop/api/controller/NoticeController.java +++ b/yami-shop-api/src/main/java/com/yami/shop/api/controller/NoticeController.java @@ -29,49 +29,70 @@ import org.springframework.web.bind.annotation.RestController; import java.util.List; /** + * 公告管理相关接口的控制器类 + * 该类提供了与公告管理相关的几个接口，包括获取置顶公告列表、获取公告详情以及获取公告分页列表等功能，通过调用服务层方法获取数据，并将结果以合适的格式返回给前端， + * 同时利用`Swagger`注解对接口进行文档化描述，方便接口的查看与使用。 + * * @author lanhai */ @RestController @RequestMapping("/shop/notice") @Tag(name = "公告管理接口") +// 使用 @AllArgsConstructor 注解，由 lombok 自动生成包含所有成员变量的构造函数，用于依赖注入 @AllArgsConstructor public class NoticeController { + // 通过构造函数注入NoticeService，用于调用业务层方法来获取公告相关的数据 private NoticeService noticeService; - - /** - * 置顶公告列表接口 + * 置顶公告列表接口方法 + * 用于获取所有置顶的公告列表信息，先从服务层获取公告列表数据，再将其转换为对应的DTO（数据传输对象）列表后返回给前端。 + * + * @return 返回一个ServerResponseEntity>类型的响应，成功时包含所有置顶公告对应的DTO列表数据，若获取数据出现异常则返回相应的错误信息。 */ @GetMapping("/topNoticeList") - @Operation(summary = "置顶公告列表信息" , description = "获取所有置顶公告列表信息") + @Operation(summary = "置顶公告列表信息", description = "获取所有置顶公告列表信息") + // 使用 @Operation 注解，在Swagger文档中对该接口进行描述，包括接口的简要总结和详细描述信息 public ServerResponseEntity> getTopNoticeList() { + // 调用服务层方法获取公告列表数据（这里获取的是所有的公告列表，后续可根据业务逻辑判断哪些是置顶的） List noticeList = noticeService.listNotice(); + // 使用 hutool 工具类的方法，将Notice类型的列表转换为NoticeDto类型的列表，用于传输给前端展示的数据格式转换 List noticeDtoList = BeanUtil.copyToList(noticeList, NoticeDto.class); return ServerResponseEntity.success(noticeDtoList); } /** - * 获取公告详情 + * 获取公告详情接口方法 + * 根据传入的公告ID，从服务层获取对应的公告详情数据，再将其转换为对应的DTO对象后返回给前端。 + * + * @param id 要获取详情的公告的唯一标识（ID），通过 @PathVariable 注解从请求路径中获取参数值。 + * @return 返回一个ServerResponseEntity类型的响应，成功时包含对应ID的公告详情对应的DTO对象数据，若获取数据出现异常则返回相应的错误信息。 */ @GetMapping("/info/{id}") - @Operation(summary = "公告详情" , description = "获取公告id公告详情") + @Operation(summary = "公告详情", description = "获取公告id公告详情") public ServerResponseEntity getNoticeById(@PathVariable("id") Long id) { + // 调用服务层方法根据ID获取公告详情数据 Notice notice = noticeService.getNoticeById(id); + // 使用 hutool 工具类的方法，将Notice对象转换为NoticeDto对象，用于传输给前端展示的数据格式转换 NoticeDto noticeDto = BeanUtil.copyProperties(notice, NoticeDto.class); return ServerResponseEntity.success(noticeDto); } /** - * 公告列表 + * 公告列表接口方法 + * 用于获取所有公告的分页列表信息，调用服务层的分页查询方法获取公告分页数据，并将结果以合适的格式返回给前端。 + * + * @param page 分页参数对象，包含了分页相关的信息，如页码、每页数量等，用于服务层进行分页查询操作。 + * @return 返回一个ServerResponseEntity>类型的响应，成功时包含符合分页条件的公告列表对应的DTO分页数据，若获取数据出现异常则返回相应的错误信息。 */ @GetMapping("/noticeList") - @Operation(summary = "公告列表信息" , description = "获取所有公告列表信息") + @Operation(summary = "公告列表信息", description = "获取所有公告列表信息") @Parameters({ }) + // 使用 @Parameters 注解，在Swagger文档中可以对接口的参数进行详细描述，这里目前没有添加具体参数描述内容 public ServerResponseEntity> pageNotice(PageParam page) { return ServerResponseEntity.success(noticeService.pageNotice(page)); } -} +} \ No newline at end of file