add swagger-api for auth, category, common and config controller

easepan · easepan · commit 5a21eea45f6c · 2018-05-30T18:29:02.000+08:00
diff --git a/src/main/java/com/zhazhapan/efo/web/controller/AuthController.java b/src/main/java/com/zhazhapan/efo/web/controller/AuthController.java
@@ -5,6 +5,10 @@
 import com.zhazhapan.efo.service.IAuthService;
 import com.zhazhapan.efo.util.ControllerUtils;
 import com.zhazhapan.util.Formatter;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
+import io.swagger.annotations.ApiOperation;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -17,32 +21,43 @@
  */
 @RestController
 @RequestMapping("/auth")
+@Api(value = "/auth", description = "权限表相关操作")
 public class AuthController {
 
     private final IAuthService authService;
 
     @Autowired
     public AuthController(IAuthService authService) {this.authService = authService;}
 
+    @ApiOperation(value = "添加权限记录", notes = "设置指定用户对指定文件的权限")
+    @ApiImplicitParams({@ApiImplicitParam(name = "files", value = "文件", example = "file1,file2,file3", required = true),
+            @ApiImplicitParam(name = "users", value = "用户", example = "user1,user2,user3", required = true),
+            @ApiImplicitParam(name = "auths", value = "权限", example = "1,1,1,1", required = true)})
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "", method = RequestMethod.POST)
     public String add(String files, String users, String auths) {
         System.out.println("files: " + files + " users: " + users + " auths: " + auths);
         return ControllerUtils.getResponse(authService.addAuth(files, users, auths));
     }
 
+    @ApiOperation(value = "获取权限记录")
+    @ApiImplicitParams({@ApiImplicitParam(name = "user", value = "用户", required = true), @ApiImplicitParam(name =
+            "file", value = "文件", required = true), @ApiImplicitParam(name = "offset", value = "偏移量", required = true)})
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "/all", method = RequestMethod.GET)
     public String getAuth(String user, String file, int offset) {
         return Formatter.listToJson(authService.getAuth(user, file, offset));
     }
 
+    @ApiOperation(value = "更新权限记录")
+    @ApiImplicitParams({@ApiImplicitParam(name = "auth", value = "权限值", required = true)})
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
     public String updateAuth(@PathVariable("id") long id, String auth) {
         return ControllerUtils.getResponse(authService.updateAuth(id, auth));
     }
 
+    @ApiOperation(value = "批量删除权限记录")
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "/batch/{ids}", method = RequestMethod.DELETE)
     public String batchDelete(@PathVariable("ids") String ids) {
diff --git a/src/main/java/com/zhazhapan/efo/web/controller/CategoryController.java b/src/main/java/com/zhazhapan/efo/web/controller/CategoryController.java
@@ -8,6 +8,9 @@
 import com.zhazhapan.modules.constant.ValueConsts;
 import com.zhazhapan.util.Checker;
 import com.zhazhapan.util.Formatter;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -20,32 +23,38 @@
  */
 @RestController
 @RequestMapping("/category")
+@Api(value = "/category", description = "文件分类相关操作")
 public class CategoryController {
 
     private final ICategoryService categoryService;
 
     @Autowired
     public CategoryController(ICategoryService categoryService) {this.categoryService = categoryService;}
 
+    @ApiOperation(value = "新增一个分类")
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "/{name}", method = RequestMethod.POST)
     public String add(@PathVariable("name") String name) {
         return ControllerUtils.getResponse(categoryService.insert(name));
     }
 
+    @ApiOperation(value = "更新分类名称")
+    @ApiImplicitParam(name = "name", value = "新的名称", required = true)
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
     public String update(@PathVariable("id") int id, String name) {
         boolean isSuccess = Checker.isNotEmpty(name) && categoryService.update(id, name);
         return ControllerUtils.getResponse(isSuccess);
     }
 
+    @ApiOperation(value = "删除一个分类")
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
     public String remove(@PathVariable("id") int id) {
         return ControllerUtils.getResponse(categoryService.remove(id));
     }
 
+    @ApiOperation(value = "获取一个分类")
     @AuthInterceptor(InterceptorLevel.NONE)
     @RequestMapping(value = "/{id}", method = RequestMethod.GET)
     public String getById(@PathVariable("id") int id) {
@@ -57,6 +66,7 @@ public String getById(@PathVariable("id") int id) {
         }
     }
 
+    @ApiOperation(value = "获取所有分类")
     @AuthInterceptor(InterceptorLevel.NONE)
     @RequestMapping(value = "/all", method = RequestMethod.GET)
     public String getAll() {
diff --git a/src/main/java/com/zhazhapan/efo/web/controller/CommonController.java b/src/main/java/com/zhazhapan/efo/web/controller/CommonController.java
@@ -9,6 +9,9 @@
 import com.zhazhapan.efo.util.ControllerUtils;
 import com.zhazhapan.modules.constant.ValueConsts;
 import com.zhazhapan.util.Checker;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -25,6 +28,7 @@
  */
 @RestController
 @RequestMapping("/common")
+@Api(value = "/common", description = "公共接口")
 public class CommonController {
 
     private static Logger logger = LoggerFactory.getLogger(ConfigController.class);
@@ -42,13 +46,16 @@ public CommonController(ICommonService commonService, HttpServletRequest request
         this.jsonObject = jsonObject;
     }
 
+    @ApiOperation(value = "获取头像资源")
     @AuthInterceptor(InterceptorLevel.NONE)
     @RequestMapping(value = "/avatar/{name}", method = RequestMethod.GET)
     public void getAvatar(HttpServletResponse response, @PathVariable("name") String name) throws IOException {
         String path = SettingConfig.getAvatarStoragePath() + ValueConsts.SEPARATOR + name;
         ControllerUtils.loadResource(response, path, ValueConsts.FALSE);
     }
 
+    @ApiOperation(value = "上传头像")
+    @ApiImplicitParam(name = "multipartFile", value = "头像", required = true)
     @AuthInterceptor(InterceptorLevel.USER)
     @RequestMapping(value = "/avatar", method = RequestMethod.POST)
     public String avatarUpload(@RequestParam("file") MultipartFile multipartFile) {
@@ -61,6 +68,7 @@ public String avatarUpload(@RequestParam("file") MultipartFile multipartFile) {
         return jsonObject.toString();
     }
 
+    @ApiOperation(value = "发送验证码")
     @AuthInterceptor(InterceptorLevel.NONE)
     @RequestMapping(value = "/{email}/code", method = RequestMethod.POST)
     public String sendVerifyCode(@PathVariable("email") String email) {
@@ -75,6 +83,7 @@ public String sendVerifyCode(@PathVariable("email") String email) {
         return jsonObject.toString();
     }
 
+    @ApiOperation(value = "验证验证码是否正确")
     @AuthInterceptor(InterceptorLevel.NONE)
     @RequestMapping(value = "/{code}/verification", method = RequestMethod.PUT)
     public String verifyCode(@PathVariable("code") String code) {
diff --git a/src/main/java/com/zhazhapan/efo/web/controller/ConfigController.java b/src/main/java/com/zhazhapan/efo/web/controller/ConfigController.java
@@ -9,6 +9,9 @@
 import com.zhazhapan.modules.constant.ValueConsts;
 import com.zhazhapan.util.FileExecutor;
 import com.zhazhapan.util.NetUtils;
+import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiOperation;
 import org.apache.log4j.Logger;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -24,10 +27,13 @@
  */
 @RestController
 @RequestMapping("/config")
+@Api(value = "/config", description = "配置文件的相关操作")
 public class ConfigController {
 
     private static Logger logger = Logger.getLogger(ConfigController.class);
+
     private final IConfigService configService;
+
     private final HttpServletRequest request;
 
     @Autowired
@@ -36,6 +42,8 @@ public ConfigController(IConfigService configService, HttpServletRequest request
         this.request = request;
     }
 
+    @ApiOperation(value = "更新配置文件")
+    @ApiImplicitParam(name = "config", value = "配置文件内容", required = true)
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "", method = RequestMethod.PUT)
     public String updateConfig(String config) {
@@ -56,6 +64,7 @@ public String updateConfig(String config) {
         }
     }
 
+    @ApiOperation(value = "获取配置文件内容")
     @AuthInterceptor(InterceptorLevel.ADMIN)
     @RequestMapping(value = "/all", method = RequestMethod.GET)
     public String getAll() {
@@ -67,12 +76,14 @@ public String getAll() {
         }
     }
 
+    @ApiOperation(value = "获取配置文件中的全局相关配置内容")
     @AuthInterceptor(InterceptorLevel.NONE)
     @RequestMapping(value = "/global", method = RequestMethod.GET)
     public String getGlobalConfig() {
         return configService.getGlobalConfig();
     }
 
+    @ApiOperation(value = "获取配置文件中的用户相关配置内容")
     @AuthInterceptor(InterceptorLevel.NONE)
     @RequestMapping(value = "/user", method = RequestMethod.GET)
     public String getUserConfig() {
