docs: 增加api文档

pom.xml

@@ -10,7 +10,7 @@
     </parent>
     <groupId>cn.seecoder</groupId>
     <artifactId>helper-backend</artifactId>
-    <version>3.0.0-SNAPSHOT</version>
+    <version>4.0.0</version>
     <packaging>jar</packaging>
     <name>helper</name>
     <description>backend</description>
@@ -125,6 +125,22 @@
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
             </plugin>
+            <plugin>
+                <groupId>com.github.apiggs</groupId>
+                <artifactId>apiggs-maven-plugin</artifactId>
+                <version>1.6</version>
+                <executions>
+                    <execution>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>apiggs</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <!-- options in there -->
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 

src/main/java/nju/seec/helper/controller/AdminController.java

@@ -18,6 +18,8 @@ import org.springframework.web.bind.annotation.*;
 import javax.servlet.http.HttpSession;
 
 /**
+ * 管理员
+ *
  * @author cst
  */
 @RestController
@@ -29,6 +31,9 @@ public class AdminController {
         this.adminService = adminService;
     }
 
+    /**
+     * 管理员登录
+     */
     @PostMapping("/login")
     public AdminVO login(@Validated @RequestBody LoginDTO loginDTO, HttpSession session) {
         AdminVO adminVO = adminService.getAdminByUsernameAndPassword(loginDTO.getUsername(), loginDTO.getPassword());
@@ -43,6 +48,9 @@ public class AdminController {
         return adminVO;
     }
 
+    /**
+     * 获取注册教师列表
+     */
     @Auth(roles = UserType.ADMIN, message = "获取注册教师列表")
     @GetMapping("/user")
     public PageResponse<UserVO> getUsers(LoginUser admin, UserType type, UserState state,
@@ -51,18 +59,27 @@ public class AdminController {
         return PageResponse.of(adminService.getUsers(type, state, key, pageable));
     }
 
+    /**
+     * 审核通过用户
+     */
     @Auth(roles = UserType.ADMIN, message = "审核通过用户")
     @PutMapping("/user/{userId}/pass")
     public void passUser(LoginUser admin, @PathVariable Long userId) {
         adminService.passUser(admin, userId);
     }
 
+    /**
+     * 封禁用户
+     */
     @Auth(roles = UserType.ADMIN, message = "封禁用户")
     @PutMapping("/user/{userId}/lock")
     public void lockUser(LoginUser admin, @PathVariable Long userId) {
         adminService.lockUser(admin, userId);
     }
 
+    /**
+     * 解封用户
+     */
     @Auth(roles = UserType.ADMIN, message = "解封用户")
     @PutMapping("/user/{userId}/unlock")
     public void unlockUser(LoginUser admin, @PathVariable Long userId) {

src/main/java/nju/seec/helper/controller/CodeController.java

@@ -27,9 +27,6 @@ public class CodeController {
 
     /**
      * 发送邮箱验证码
-     *
-     * @param email
-     * @return
      */
     @PostMapping("/email")
     public void sendEmailCode(@NotBlank(message = "邮箱不能为空") @SchoolEmail String email) {
@@ -38,9 +35,6 @@ public class CodeController {
 
     /**
      * 发送手机验证码
-     *
-     * @param phone
-     * @return
      */
     @PostMapping("/phone")
     public void sendPhoneCode(@NotBlank(message = "手机号不能为空") @Phone String phone) {

src/main/java/nju/seec/helper/controller/CommentController.java

@@ -81,7 +81,7 @@ public class CommentController {
     }
 
     /**
-     * 取得某评论
+     * 取得某一评论
      */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获取评论")
     @GetMapping("/{commentId}")

src/main/java/nju/seec/helper/controller/CourseController.java

@@ -131,6 +131,9 @@ public class CourseController {
         return courseService.getOneCourse(courseId);
     }
 
+    /**
+     * 获取选课名单
+     */
     @Auth(roles = UserType.TEACHER, message = "获取选课名单")
     @GetMapping("/{courseId}/students")
     public PageResponse<UserVO> getChooseStudents(LoginUser user,

src/main/java/nju/seec/helper/controller/CourseFileController.java

@@ -13,6 +13,8 @@ import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
 /**
+ * 课程附件
+ *
  * @author cst
  */
 @RestController
@@ -24,6 +26,9 @@ public class CourseFileController {
         this.courseFileService = courseFileService;
     }
 
+    /**
+     * 上传课程附件
+     */
     @Auth(roles = UserType.TEACHER, message = "上传课程附件")
     @PostMapping
     public void uploadCourseFile(LoginUser user,
@@ -31,6 +36,9 @@ public class CourseFileController {
         courseFileService.uploadCourseFile(user, courseFileDTO);
     }
 
+    /**
+     * 删除课程附件
+     */
     @Auth(roles = UserType.TEACHER, message = "删除课程附件")
     @DeleteMapping("/{courseFileId}")
     public void deleteCourseFile(LoginUser user,
@@ -38,6 +46,9 @@ public class CourseFileController {
         courseFileService.deleteCourseFile(user, courseFileId);
     }
 
+    /**
+     * 获取课程附件
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获取课程附件")
     @GetMapping("/course/{courseId}")
     public PageResponse<CourseFileVO> getCourseFilesByCourse(LoginUser user,
@@ -47,6 +58,9 @@ public class CourseFileController {
         return PageResponse.of(courseFileService.getCourseFilesByCourse(user, courseId, key, pageable));
     }
 
+    /**
+     * 获取课程附件链接
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获取课程附件链接")
     @GetMapping("/{courseFileId}/url")
     public String getOneCourseFile(LoginUser user,

src/main/java/nju/seec/helper/controller/MessageController.java

@@ -13,6 +13,8 @@ import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
 /**
+ * 消息
+ *
  * @author cst
  */
 @RestController
@@ -24,6 +26,9 @@ public class MessageController {
         this.messageService = messageService;
     }
 
+    /**
+     * 设置已读
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "设置已读")
     @PutMapping("/read")
     public void readMessages(LoginUser user,
@@ -31,6 +36,9 @@ public class MessageController {
         messageService.readMessages(user, messageDTO);
     }
 
+    /**
+     * 删除消息
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "删除消息")
     @PutMapping("/delete")
     public void deleteMessages(LoginUser user,
@@ -38,6 +46,9 @@ public class MessageController {
         messageService.deleteMessages(user, messageDTO);
     }
 
+    /**
+     * 获取未读消息
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获取未读消息")
     @GetMapping("/unread")
     public PageResponse<Message> getUnreadMessages(LoginUser user,
@@ -46,6 +57,9 @@ public class MessageController {
         return PageResponse.of(messageService.getUnreadMessages(user, key, pageable));
     }
 
+    /**
+     * 获取已读消息
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获取已读消息")
     @GetMapping("/read")
     public PageResponse<Message> getReadMessages(LoginUser user,

src/main/java/nju/seec/helper/controller/NoticeController.java

@@ -15,6 +15,8 @@ import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
 /**
+ * 公告
+ *
  * @author cst
  */
 @RestController
@@ -26,6 +28,13 @@ public class NoticeController {
         this.noticeService = noticeService;
     }
 
+    /**
+     * 发布公告
+     *
+     * @param user
+     * @param noticeDTO
+     * @return
+     */
     @Auth(roles = UserType.TEACHER, message = "发布公告")
     @PostMapping
     public NoticeVO createNotice(LoginUser user,
@@ -33,6 +42,14 @@ public class NoticeController {
         return noticeService.createNotice(user, noticeDTO);
     }
 
+    /**
+     * 修改公告
+     *
+     * @param user
+     * @param noticeId
+     * @param noticeDTO
+     * @return
+     */
     @Auth(roles = UserType.TEACHER, message = "修改公告")
     @PutMapping("/{noticeId}")
     public NoticeVO modifyNotice(LoginUser user,
@@ -41,6 +58,9 @@ public class NoticeController {
         return noticeService.modifyNotice(user, noticeId, noticeDTO);
     }
 
+    /**
+     * 删除公告
+     */
     @Auth(roles = UserType.TEACHER, message = "删除公告")
     @DeleteMapping("/{noticeId}")
     public void deleteNotice(LoginUser user,
@@ -48,6 +68,9 @@ public class NoticeController {
         noticeService.deleteNotice(user, noticeId);
     }
 
+    /**
+     * 获取课程公告
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获取课程公告")
     @GetMapping("/course/{courseId}")
     public PageResponse<NoticeVO> getNotices(LoginUser user,
@@ -57,6 +80,9 @@ public class NoticeController {
         return PageResponse.of(noticeService.getNoticesByCourse(user, courseId, key, pageable));
     }
 
+    /**
+     * 获取某一公告
+     */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获取公告")
     @GetMapping("/{noticeId}")
     public NoticeVO getOneNotice(LoginUser user,

src/main/java/nju/seec/helper/controller/QuestionController.java

@@ -44,7 +44,7 @@ public class QuestionController {
     }
 
     /**
-     * 某一测试的题目
+     * 获取某一测试题目
      */
     @Auth(roles = {UserType.TEACHER, UserType.STUDENT}, message = "获得测试题目")
     @GetMapping("/quiz/{quizId}")
@@ -52,30 +52,45 @@ public class QuestionController {
         return questionService.getQuestionsByQuiz(user, quizId);
     }
 
+    /**
+     * 获取某一题目信息
+     */
     @Auth(roles = UserType.TEACHER, message = "获取题目信息")
     @GetMapping("/{questionId}")
     public BaseQuestionVO getOneQuestion(LoginUser user, @PathVariable String questionId) {
         return questionService.getOneQuestion(user, questionId);
     }
 
+    /**
+     * 创建题目
+     */
     @Auth(roles = UserType.TEACHER, message = "创建题目")
     @PostMapping
     public BaseQuestionVO createQuestion(LoginUser user, @Validated(Create.class) @RequestBody BaseQuestionDTO baseQuestionDTO) {
         return questionService.createQuestion(user, baseQuestionDTO);
     }
 
+    /**
+     * 修改题目
+     */
     @Auth(roles = UserType.TEACHER, message = "修改题目")
     @PutMapping("/{questionId}")
     public BaseQuestionVO modifyQuestion(LoginUser user, @PathVariable String questionId, @Validated(Modify.class) @RequestBody BaseQuestionDTO baseQuestionDTO) {
         return questionService.modifyQuestion(user, questionId, baseQuestionDTO);
     }
 
+    /**
+     * 删除题目
+     */
     @Auth(roles = UserType.TEACHER, message = "删除题目")
     @DeleteMapping("/{questionId}")
     public void deleteQuestion(LoginUser user, @PathVariable String questionId) {
         questionService.deleteQuestion(user, questionId);
     }
 
+    /**
+     * 获取创建题目
+     */
     @Auth(roles = UserType.TEACHER, message = "获取创建的题目")
     @GetMapping("/created")
     public PageResponse<BaseQuestionVO> getCreatedQuestions(LoginUser user,
@@ -83,6 +98,9 @@ public class QuestionController {
         return PageResponse.of(questionService.getCreatedQuestions(user, pageable));
     }
 
+    /**
+     * 获取创建题目ID
+     */
     @Auth(roles = UserType.TEACHER)
     @GetMapping("/created/ids")
     public Set<String> getCreatedQuestionIds(LoginUser user) {

src/main/java/nju/seec/helper/controller/QuizController.java

@@ -110,6 +110,9 @@ public class QuizController {
         quizService.deleteQuiz(user, Long.valueOf(quizId));
     }
 
+    /**
+     * 提交作答
+     */
     @Auth(roles = {UserType.STUDENT}, message = "提交作答")
     @PostMapping("/{quizId}/student-answer")
     public QuizStudentAnswerVO submitQuizStudentAnswer(LoginUser user, @PathVariable Long quizId, @RequestBody QuizStudentAnswerDTO quizStudentAnswerDTO) {
@@ -117,11 +120,7 @@ public class QuizController {
     }
 
     /**
-     * 老师获取某一测试学生的作答列表
-     *
-     * @param user
-     * @param quizId
-     * @return
+     * 获取测试作答列表
      */
     @Auth(roles = {UserType.TEACHER}, message = "获取学生作答")
     @GetMapping("/{quizId}/student-answers")
@@ -131,10 +130,6 @@ public class QuizController {
 
     /**
      * 学生获取某一测试自己的作答
-     *
-     * @param user
-     * @param quizId
-     * @return
      */
     @Auth(roles = {UserType.STUDENT}, message = "获取作答")
     @GetMapping("/{quizId}/student-answer")
@@ -142,6 +137,9 @@ public class QuizController {
         return quizStudentAnswerService.getQuizStudentAnswer(user, quizId);
     }
 
+    /**
+     * 获取测试作答提交的统计信息
+     */
     @Auth(roles = {UserType.TEACHER}, message = "获取测试统计消息")
     @GetMapping("/{quizId}/statistic")
     public QuizStudentAnswerStatisticVO getQuizStatistic(LoginUser user, @PathVariable Long quizId) {

src/main/java/nju/seec/helper/controller/ReplyController.java

@@ -10,6 +10,8 @@ import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
 /**
+ * 回复
+ *
  * @author cst
  */
 @RestController

src/main/java/nju/seec/helper/controller/UserController.java

@@ -3,9 +3,9 @@ package nju.seec.helper.controller;
 import com.google.common.collect.ImmutableMap;
 import nju.seec.helper.aspect.auth.Auth;
 import nju.seec.helper.aspect.auth.LoginUser;
+import nju.seec.helper.dto.common.LoginDTO;
 import nju.seec.helper.dto.groups.Create;
 import nju.seec.helper.dto.groups.Modify;
-import nju.seec.helper.dto.common.LoginDTO;
 import nju.seec.helper.dto.user.ResetPasswordDTO;
 import nju.seec.helper.dto.user.UserDTO;
 import nju.seec.helper.enums.ExceptionType;

src/main/java/nju/seec/helper/util/RedisCacheUtils.java

@@ -2,10 +2,8 @@ package nju.seec.helper.util;
 
 import org.springframework.data.redis.core.RedisTemplate;
 import org.springframework.stereotype.Component;
-import sun.reflect.generics.reflectiveObjects.NotImplementedException;
 
 import java.util.List;
-import java.util.Map;
 import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 
@@ -26,10 +24,6 @@ public class RedisCacheUtils {
         redisTemplate.opsForValue().set(combineKey(cacheName, key), value, expireTime, timeUnit);
     }
 
-    public void setAll(String cacheName, Map<String, String> putAll, long expireTime, TimeUnit timeUnit) {
-        throw new NotImplementedException();
-    }
-
     public String get(String cacheName, String key) {
         return redisTemplate.opsForValue().get(combineKey(cacheName, key));
     }