乐趣区

关于swagger:SpringBoot中优雅的使用Swagger2史上最全注解篇22

jiezi

上篇文章讲到 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 注解 后，你们写的接口是不是被好多共事夸赞了呢？哈哈哈。

感激浏览小生文章。祝大家 早日富可敌国，实现财产自在。

记得 点赞、评论、珍藏哦。

有任何问题能够在微信搜寻 公众号 ：Madison 龙少 进行征询

或者微信扫描上面二维码进行征询

退出移动版