需要有 ： “方法简要说明” + “参数说明” + “返回值说明”， 对于返回值类型为Map的注释编写举例如下：
返回一个对象 /** * 方法简要说明 * * @param param * param说明 * @return * * <pre> * { * "key1": "string", * "key2": "integer", * "key3": "boolean", * "key4": "double", * "key5": "date", * "key6": "byte[]", * "key7": "long", * "key8": "decimal", * ...... * } * </pre> */ 返回一个级联对象 /** * 方法简要说明 * * @param param * param说明 * @return * * <pre> * Aa * { * "bb": "object", * ...... * } * Bb * { * "cc": "object", * ...... * } * Cc * { * ...... * } * </pre> */ 返回对象数组 /** * 方法简要说明 * * @param param * param说明 * @return * * <pre> * [ * { * "bb": "object", * ...... * }, * ...... * ] * Bb * { * "cc": "object", * ...... * } * Cc * { * ...... * } * </pre> */返回值： Boolean 方法名： 对象名+字段名+NoRepeat (驼峰命名)
/** * 医院名称不重复 * * @param hospitalName * 医院名称 * @return */ public Boolean hospitalNameNoRepeat(String hospitalName) { Map<String, Object> hospital = hospitalDao.selectHospitalByName(hospitalName); if (hospital != null) { return Boolean.FALSE; } return Boolean.TRUE; }必须添加@Transaction注解声明事务
@PathVariable 注解，如果value值和参数名是相同的，不准加参数（例如：@PathVariable String username 不要@PathVariable(value = “username”) String username或者@PathVariable(“username”) String username）
代码示例： @ApiOperation("分页查询用户") @GetMapping("/users") public Object getUsersPage(@RequestParam("username") String name, Page page) { username = ParamUtils.escape(username); PageInfo<Map<String, String>> usersPage = userService.getUsersPage(page, username); return usersPage; } 2. 添加 1. URI中名词用复数形式 2. 方法返回值用Object, Http动词使用POST请求，即@PostMapping注解。 * 不准使用GET、PUT、DELETE、PATCH等动词 * 不准使用@RequestMapping注解 3. 方法参数必须使用@RequestBody注解，不准使用@RequestParam注解 4. 返回值： 成功返回ResponseWrapper.buildSuccess()，失败无需处理 5. 方法名： add开头+URI单数形式 6. 对于添加多个采用多次调用添加一个的方式，对于特殊批量新增接口另行处理 代码示例： @ApiOperation("添加角色") @PostMapping("/roles") public Object addRole(@RequestBody JSONObject userJson) { return ResponseWrapper.buildSuccess(); } 3. 修改 1. URI中名词用复数形式+要修改的对象id 2. 方法返回值用Object, Http动词使用PUT请求，即@PutMapping注解。 * 不准使用GET、POST、DELETE、PATCH等动词 * 不准使用@RequestMapping注解 3. 方法参数必须使用@RequestBody注解，不准使用@RequestParam注解 4. 返回值： 成功返回ResponseWrapper.buildSuccess()，失败无需处理 5. 方法名： update开头+URI单数形式 6. 对于修改多个采用多次调用修改一个的方式，对于特殊批量修改接口另行处理 代码示例： @ApiOperation("修改用户") @PutMapping("/users/{id}") public Object updateRole(@RequestBody JSONObject userJson, @PathVariable("id") String userId) { return ResponseWrapper.buildSuccess(); } 4. 删除 1. URI中名词用复数形式+要修改的对象id 2. 方法返回值用Object, Http动词使用DELETE请求，即@DeleteMapping注解。 * 不准使用GET、POST、PUT、PATCH等动词 * 不准使用@RequestMapping注解 3. 方法参数必须使用@RequestBody注解，不准使用@RequestParam注解 4. 返回值： 成功返回ResponseWrapper.buildSuccess()，失败无需处理 5. 方法名： delete开头+URI单数形式 6. 对于删除多个采用多次调用删除一个的方式，对于特殊批量删除接口另行处理 代码示例： @ApiOperation("删除用户") @DeleteMapping("/users/{id}") public Object deleteUser(@PathVariable("id") String userId) { userService.deleteUser(userId); return ResponseWrapper.buildSuccess(); } 5. 字段不重复校验 1. URI中使用"/no-repeat/" + 要校验的对象和字段名（多个单词采用横线-连接）+ "/{name}" 2. 方法返回值用Boolean, Http动词使用GET请求，即@GetMapping注解。 * 不准使用DELETE、POST、PUT、PATCH等动词 * 不准使用@RequestMapping注解 3. 方法参数必须使用@PathVariable注解，不准使用@RequestParam注解或@RequestBody注解 4. 方法名： 字段名驼峰+NoRepeat 5. 强制：对于Service中用到的boolean类型全部提升为Boolean包装类（虽然jdk1.6提供自动装箱和拆箱工作） @ApiOperation("字典类型值不重复") @GetMapping("/no-repeat/dict-type-value/{name}") public Boolean dictTypeValueNoRepeat(@PathVariable("name") String name) { return dictService.dictTypeValueNoRepeat(name); } 6. 参数校验 1. 对于Controller入口必须进行参数校验 2. 对于校验出错的直接抛异常。例如throw new ParamException(key + "不能为空"); 3. PramUtils提供基础的参数处理工具 4. 对于@PathVariable参数必须使用正则校验 5. 对于@RequestParam、@RequestBody参数可以使用自定义方法校验，也可以使用JSR303标准校验