SpringBoot中优雅的使用Swagger2【史上最全注解篇】-【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 = "详细描述: 方法详细描述信息")
@GetMapping("/")
public String login(String... index) {
    return "Hello login ~";
}
value:用来对接口的总体描述

notes:用来对接口的详细描述

SpringBoot中优雅的使用Swagger2【史上最全注解篇】-【2/2】_第1张图片

@ApiImplicitParams

作用:用来对接口中参数进行说明

修饰范围:作用在方法上

参数:@ApiImplicitParam数组

@ApiImplicitParam

作用:修饰接口方法里面的参

修饰范围:作用方法上

参数

  • name:方法参数名称
  • value:方法参数的描述
  • dataType:方法参数数据类型
  • defaultValue :方法参数默认值(给测试人员做测试用的)
  • paramType
    • 默认query:对应方式一

      • path:对应方式二
    • body:对应方式三

SpringBoot中优雅的使用Swagger2【史上最全注解篇】-【2/2】_第2张图片

方式一: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 = "实体类描述")

SpringBoot中优雅的使用Swagger2【史上最全注解篇】-【2/2】_第3张图片

@ApiModelProperty

作用:用来对实体类中的属性进行说明

修饰范围:作用在类中的属性上
@ApiModelProperty(value = "类属性描述",required = true,example = "属性举例",notes = "备注")

结束语

 至此 springboot集成swagger2就讲完了,我相信,看完我这两篇文章之后的朋友,你们就能很熟练的在java代码中使用swagger了。

 因为目前 前后端分离比较流行,所以写一个好的 swagger接口文档是很有必要的,这样就会减少前后端因为一些接口表述不清楚,导致的后端开发人员来回和前端人员交流沟通,大大的提高了开发的效率。

 使用 swagger注解后,你们写的接口是不是被好多同事夸奖了呢?哈哈哈。

感谢阅读小生文章。祝大家早日富可敌国,实现财富自由

记得点赞、评论、收藏哦

有任何问题可以在微信搜索公众号Madison龙少进行咨询

或者微信扫描下面二维码进行咨询

你可能感兴趣的:(SpringBoot中优雅的使用Swagger2【史上最全注解篇】-【2/2】)