Update NoticeController.java

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<List<NoticeDto>>类型的响应，成功时包含所有置顶公告对应的DTO列表数据，若获取数据出现异常则返回相应的错误信息。
      */
     @GetMapping("/topNoticeList")
-    @Operation(summary = "置顶公告列表信息" , description = "获取所有置顶公告列表信息")
+    @Operation(summary = "置顶公告列表信息", description = "获取所有置顶公告列表信息")
+    // 使用 @Operation 注解，在Swagger文档中对该接口进行描述，包括接口的简要总结和详细描述信息
     public ServerResponseEntity<List<NoticeDto>> getTopNoticeList() {
+        // 调用服务层方法获取公告列表数据（这里获取的是所有的公告列表，后续可根据业务逻辑判断哪些是置顶的）
         List<Notice> noticeList = noticeService.listNotice();
+        // 使用 hutool 工具类的方法，将Notice类型的列表转换为NoticeDto类型的列表，用于传输给前端展示的数据格式转换
         List<NoticeDto> noticeDtoList = BeanUtil.copyToList(noticeList, NoticeDto.class);
         return ServerResponseEntity.success(noticeDtoList);
     }
 
     /**
-     * 获取公告详情
+     * 获取公告详情接口方法
+     * 根据传入的公告ID，从服务层获取对应的公告详情数据，再将其转换为对应的DTO对象后返回给前端。
+     *
+     * @param id 要获取详情的公告的唯一标识（ID），通过 @PathVariable 注解从请求路径中获取参数值。
+     * @return 返回一个ServerResponseEntity<NoticeDto>类型的响应，成功时包含对应ID的公告详情对应的DTO对象数据，若获取数据出现异常则返回相应的错误信息。
      */
     @GetMapping("/info/{id}")
-    @Operation(summary = "公告详情" , description = "获取公告id公告详情")
+    @Operation(summary = "公告详情", description = "获取公告id公告详情")
     public ServerResponseEntity<NoticeDto> 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<IPage<NoticeDto>>类型的响应，成功时包含符合分页条件的公告列表对应的DTO分页数据，若获取数据出现异常则返回相应的错误信息。
      */
     @GetMapping("/noticeList")
-    @Operation(summary = "公告列表信息" , description = "获取所有公告列表信息")
+    @Operation(summary = "公告列表信息", description = "获取所有公告列表信息")
     @Parameters({
     })
+    // 使用 @Parameters 注解，在Swagger文档中可以对接口的参数进行详细描述，这里目前没有添加具体参数描述内容
     public ServerResponseEntity<IPage<NoticeDto>> pageNotice(PageParam<NoticeDto> page) {
 
         return ServerResponseEntity.success(noticeService.pageNotice(page));
     }
-}
+}