swagger的详细解释

​

作用范围	API	API常用参数	作用位置
协议集描述	@Api	@Api(tags = {"tag1","tag2","..."})	controller类
协议描述	@ApiOperation	@ApiOperation(value = "功能描述",notes = "备注")	controller类的方法
描述返回对象的意义	@ApiModel	@ApiModel(value="类名",description="类描述")	返回对象类
对象属性	@ApiModelProperty	@ApiModelProperty(value = "类属性描述",required = true,example = "属性举例",notes = "备注")	出入参数对象的字段
非对象参数集	@ApiImplicitParams	@ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam(),...})	controller的方法
非对象参数描述	@ApiImplicitParam	@ApiImplicitParam(name = "参数名",value = "参数描述",required = true,paramType = "接口传参类型",dataType = "参数数据类型")	@ApiImplicitParams的方法里用
Response集	@ApiResponses	@ApiResponses({ @ApiResponse(),@ApiResponse(),..})	controller的方法
Response	@ApiResponse	@ApiResponse(code = 10001, message = "返回信息")	@ApiResponses里用
忽略注解	@ApiIgnore	@ApiIgnore	类，方法，方法参数

API使用详细说明

@Api

• 作用：用来指定接口的描述文字
• 修饰范围：作用在类上

@Api(tags = "StudentController测试")
@RestController
public class StudentController{
    ....
}

@ApiOperation

• 作用：用来对接口中具体方法做描述
• 修饰范围：作用在方法上

 @ApiOperation(value = "获取所有学生",notes = "获取所有表中学生实体")
    @RequestMapping(value = "/getall",method = RequestMethod.GET)
    public List<Student> getAll(){
        List<Student> students=studentDao.getAll();
        return students;
    }

value：用来对接口的总体描述
notes：用来对接口的详细描述

@ApiImplicitParams

• 作用：用来对接口中参数进行说明
• 修饰范围：作用在方法上
  参考：@ ApiImplicitParam数组

@ApiImplicitParam

• 作用：修饰接口方法里面的参数
• 修饰范围：作用方法上

参数：

1. name：方法参数名称
2. value：方法参数的描述
3. dataType：方法参数数据类型
4. defaultValue ：方法参数默认值（给测试人员做测试用的）

paramType ：

1. 默认query：对应方式一
2. path：对应方式二
3. body：对应方式三

方式一：url？id=1&user='qlh'后面参数

@ApiOperation(value = "接口总体描述", notes = "方法详细描述信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", dataType = "String", defaultValue = "qlh"),
        @ApiImplicitParam(name = "password", value = "密码", dataType = "String", defaultValue = "123")
})
@PostMapping("/")
public String login(String username, String password) {
    return "Hello login ~";
}

方式二：url/1/2路径后 传参 在路径中获取参数

@ApiOperation(value = "接口总体描述", notes = "方法详细描述信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "id", dataType = "String", defaultValue = "qlh",paramType = "path"),
        @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", defaultValue = "123",paramType = "path")
})
@PostMapping("/index/{id}/{name}")
public String index(@PathVariable("id") String id, @PathVariable("name") String name) {
    return "Hello World ~";
}

方式三：在body中传参

@ApiOperation(value = "接口总体描述", notes = "方法详细描述信息")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "id", dataType = "String", defaultValue = "xxx", paramType = "body"),
        @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", defaultValue = "123", paramType = "body")
})
@PostMapping("/index")
public String index(@RequestBody Map<String, Object> map) {
    return "Hello World ~";
}

@ApiResponses

• 作用：用于接口的响应结果
• 修改范围：作用在接口方法上

@ApiResponses({
        @ApiResponse(),
        @ApiResponse(),
        ...
})

@ApiResponse

• 作用：在ApiResponses里面对响应码以及响应内容进行设置
• 修饰范围：作用接口方法上
• 参数：
  code：响应状态码
  message：响应状态码对应的响应内容

@ApiResponse(code = 10001, message = "签名错误"),
@ApiResponse(code = 10002, message = "sql错误"),
@ApiResponse(code = 10003, message = "服务怠机,请稍后重试"),

@ApiIgnore

• 作用：忽略类，方法，参数。（忽略的意思：在 swagger-ui.html中不显示）
• 修改范围：作用在类，方法，参数上

@ApiIgnore

实体类中swagger注解

@ApiModel

• 作用：用来对实体类进行说明
• 修饰范围：作用在类上

@ApiModel(value="类名",description = "实体类描述")

@ApiModelProperty

• 作用：用来对实体类中的属性进行说明
• 修饰范围：作用在类中的属性上

@ApiModelProperty(value = "类属性描述",required = true,example = "属性举例",notes = "备注")