上篇文章讲到 SpringBoot中优雅的使用Swagger2-【1/2】，还不会使用Swagger的小伙伴可以先去看上期文章。
API使用说明
| 作用范围 | 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 = "TestController测试")
@RestController
public class TestController {
....
}
@ApiOperation
作用：用来对接口中具体方法做描述
修饰范围：作用在方法上
@ApiOperation(value = "接口总体描述",notes = "详细描述： 方法详细描述信息")
@GetMapping("/")
public String login(String... index) {
return "Hello login ~";
}value：用来对接口的总体描述
notes：用来对接口的详细描述
@ApiImplicitParams
作用：用来对接口中参数进行说明修饰范围：作用在方法上参数：@ApiImplicitParam数组@ApiImplicitParam
作用：修饰接口方法里面的参修饰范围：作用方法上参数：
name：方法参数名称value：方法参数的描述dataType：方法参数数据类型defaultValue：方法参数默认值（给测试人员做测试用的）paramType：
默认query：对应方式一
path：对应方式二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 map) {
return "Hello World ~";
} @ApiResponses
作用：用于接口的响应结果
修改范围：作用在接口方法上
参数：@ApiResponse数组
@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 = "备注")
结束语
至此springboot集成swagger2就讲完了，我相信，看完我这两篇文章之后的朋友，你们就能很熟练的在java代码中使用swagger了。
因为目前前后端分离比较流行，所以写一个好的swagger接口文档是很有必要的，这样就会减少前后端因为一些接口表述不清楚，导致的后端开发人员来回和前端人员交流沟通，大大的提高了开发的效率。
使用swagger注解后，你们写的接口是不是被好多同事夸奖了呢？哈哈哈。感谢阅读小生文章。祝大家
早日富可敌国，实现财富自由。
记得点赞、评论、收藏哦。
有任何问题可以在微信搜索公众号：Madison龙少进行咨询
或者微信扫描下面二维码进行咨询
