Swagger注释@API详细说明-CFANZ编程社区

前言：
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实一个好接口文档很重要，对项目开发起着很重要的作用。正好有这样一个开源API文档生成的项目，完美解决了接口文档的问题，下面我们就简单的了解一下。

Swagger介绍

swagger是当前最好用的Restful API文档生成的开源项目。
通过这套规范，你只需要按照他的规范去定义接口相关的信息。再通过Swagger衍生出来一系列项目和工具，就可以做到生成格式的接口文档。

相关注解说明

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在参数对象的字段上
协议集描述	@Api	用在Controller类上
协议描述	@ApiOperation	用在controller方法上
Response集	@ApiResponses	用在controller方法上
Response	@ApiResponse	用在@ApiResponses里面
非对象参数集	@ApilmplicitParams	用在controller方法上
非对象参数描述	@ApilmplicitParam	用在@ApilmplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

@API
tags：表示说明，
value: 字段说明，
description：注释说明这个类

@Api(tags = "PmsBrandController", description = "商品品牌管理")
@Controller
@RequestMapping("/brand")
public class PmsBrandController {}

@ApiOperation
value: 字段说明
notes: 注释说明
httpMethod: 说明这个方法被请求的方式
response: 方法的返回值的类型

@ApiOperation("获取所有品牌列表")
    @RequestMapping(value = "listAll", method = RequestMethod.GET)
    @ResponseBody
    @PreAuthorize("hasAuthority('pms:brand:read')")
    public CommonResult<List<PmsBrand>> getBrandList() {
        return CommonResult.success(brandService.listAllBrand());
    }

@ApiResponse
code: 响应的HTTP状态码
message: 响应的信息内容
@ApiModelProperty
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

/**
     * 获取学生编号
     * @return 学生编号
     */
    @ApiModelProperty(value="学生编号",example="058",required=true)
    public String getCode() {
        return code;
    }