Spring Boot 中优雅的使用 Swagger 2-2（史上最全注解篇）

上篇文章讲到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 = "<span style='color:red;'>详细描述：</span>&nbsp;方法详细描述信息")
@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 = "<span style='color:red;'>详细描述：</span>&nbsp;方法详细描述信息")
@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 = "<span style='color:red;'>详细描述：</span>&nbsp;方法详细描述信息")
@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 = "<span style='color:red;'>详细描述：</span>&nbsp;方法详细描述信息")
@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

作用：用于接口的响应结果
修改范围：作用在接口方法上
参数：@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注解后，你们写的接口是不是被好多同事夸奖了呢？哈哈哈。

看完三件事❤️

如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：

1. 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。

2. 关注公众号 『 java烂猪皮 』，不定期分享原创知识。

3. 同时可以期待后续文章ing🚀

4. .关注后回复【666】扫码即可获取学习资料包

作者：Madison龙少

出处：toutiao.io/posts/2qkwu…