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 = "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接口文档是很有必要的，这样就会减少前后端因为一些接口表述不清楚，导致的后端开发人员来回和前端人员交流沟通，大大的提高了开发的效率。