Swagger的三个常用注解

1. @Api

用于修饰类，在qs项目中用于描述Controller

参数：description 用于对该类的定义或描述该类的作用

@Api(description = "备忘录相关接口")
@RestController
public class MemoController {

    private final MemoRepository memoRepository;

    @Autowired
    public MemoController(MemoRepository memoRepository) {
        this.memoRepository = memoRepository;
    }

2. @ApiOperation

用于修饰方法或接口

参数：value = "  ", 对方法的简述

    note = "  ", 对方法或接口的具体描述

/**
 * 查询
 *
 * @return
 */
@ApiOperation(value="根据用户id获取备忘录列表", notes="获取当前用户的所有备忘录")
@RequestMapping(value = "/{userId}/memos", method = RequestMethod.GET)
public ResultData list(
        @ApiParam(required = true, value = "用户id") @PathVariable("userId") String userId) {

    List<Memo> memos = memoRepository.findByUserId(userId);

    return ResultData.ok()
            .putDataValue("memos", memos);
}

3. @ApiParam

用于对每个参数的描述

参数：required = true,  表示该参数是必要参数。

    value, 对参数的描述

注：Swagger对所有参数是可选的(required可以是false),

但是当参数作为路径参数总是必须的，也就是说当参数出现在路径中时，required必须为true。

如下图代码中的userId.

/**
 * 按照memoId查找
 *
 * @param id
 * @return
 */
@ApiOperation(value="根据备忘录id获取备忘录信息", notes="获取当前备忘录信息")
@RequestMapping(value = "/{userId}/memos/{id}", method = RequestMethod.GET)
public ResultData find(
        @ApiParam(required = true, value = "用户id") @PathVariable("userId") String userId,
        @ApiParam(required = true, value = "备忘录id") @PathVariable("id") String id) {
    Memo memo = memoRepository.findOne(id);
    return ResultData.ok()
            .putDataValue("memo", memo);
}

其他注解可参考http://www.cnblogs.com/java-zhao/p/5348113.html