Swagger笔记
简介
-
由于架构革新,进入了前后端分离,服务端只需提供RESTful API的时代。
-
而构建RESTful API会考虑到多终端的问题,这样就需要面对多个开发人员甚至多个开发团队。
-
为了减少与其他团队对接的沟通成本,我们通常会写好对应的API接口文档。
-
从最早开始的word文档,到后续的showdoc,都能减少很多沟通成本,但随之带来的问题也比较麻烦。在开发期间接口会因业务的变更频繁而变动,如果需要实时更新接口文档,这是一个费时费力的工作。
-
为了解决上面的问题,Swagger应运而生。他可以轻松的整合进框架,并通过一系列注解生成强大的API文档。他既可以减轻编写文档的工作量,也可以保证文档的实时更新,将维护文档与修改代码融为一体,是目前较好的解决方案。
常用注解
-
@Api
-
用于类,表示标识这个类是swagger的资源
-
tags 表示说明
-
value 也是说明,可以使用tags替代
但是tags如果有多个值,会生成多个list
-
-
@ApiOperationSupport
-
用于方法,在swagger上的先后顺序
-
-
@ApiOperation
-
用于方法,表示一个http请求的操作
-
@Api(value = "Exchange", tags = "Exchange接口") public class ExchangeController extends BladeController { @Autowired private final IExchangeService iExchangeService; @PostMapping("/save") @ApiOperationSupport(order = 1) @ApiOperation(value = "新增", notes = "传入exchange") public R<Exchange> save(@Valid @RequestBody Exchange exchange) { return R.status(iExchangeService.save(exchange)); } }
-
@ApiParam
-
用于方法,参数,字段说明,表示对参数的添加元数据(说明或是否必填等)
-
name 参数名
-
value 参数说明
-
required 是否必填
-
@PostMapping("/remove") @ApiOperation(value = "逻辑删除", notes = "传入notice") public R remove(@ApiParam(value = "主键集合") @RequestParam String ids) { boolean temp = noticeService.deleteLogic(Func.toIntList(ids)); return R.status(temp); }
-
@ApiModel
-
用于类 ,表示对类进行说明,用于参数用实体类接收
-
value 表示对象名
-
description 描述
-
都可省略
-
-
@ApiModelProperty
-
用于方法,字段,表示对model属性的说明或者数据操作更改
-
value 字段说明
-
name 重写属性名字
-
dataType 重写属性类型
-
required 是否必填
-
example 举例说明
-
hidden 隐藏
-
@Data @TableName("hr_exchange") @EqualsAndHashCode(callSuper = true) @ApiModel(value = "exchange对象", description = "exchange对象") public class Exchange extends BaseEntity implements Serializable { private static final long serialVersionUID = 1L; /** * 主键 */ @JsonSerialize(using = ToStringSerializer.class) @ApiModelProperty(value = "主键") @TableId(value = "id", type = IdType.ASSIGN_ID) private Long id; }
-
@ApiIgnore()
-
用于类,方法,方法参数,表示这个方法或者类被忽略
-
@ApiIgnore() @GetMapping("/detail") public R<Notice> detail(Integer id) { Notice detail = noticeService.getOne(id); return R.data(detail ); }
-
@ApiImplicitParams()
-
用于方法,包含一组参数说明 @ApiImplicitParam
-
-
@ApiImplicitParam()
-
用于方法,指定一个请求参数的各个方面
-
paramType:参数放在哪个地方
-
header-->请求参数的获取:@RequestHeader
-
query-->请求参数的获取:@RequestParam
-
path(用于restful接口)-->请求参数的获取:@PathVariable
-
body(不常用)
-
form(不常用)
-
name:参数名
-
dataType:参数类型
-
required:参数是否必须传
-
value:参数的意思
-
defaultValue:参数的默认值
-
@GetMapping("/list") @ApiImplicitParams({ @ApiImplicitParam(name = "category",value = "公告类型", paramType = "query", dataType = "integer"), @ApiImplicitParam(name = "title",value = "公告标题", paramType = "query", dataType = "string")}) @ApiOperation(value = "分页", notes = "传入notice") public R<IPage<Notice>> list(@ApiIgnore @RequestParam Map<String, Object> notice, Query query) { IPage<Notice> pages = noticeService.page(Condition.getPage(query), Condition.getQueryWrapper(notice, Notice.class)); return R.data(pages ); }
-
@ApiResponses
-
用于表示一组响应
-
-
@ApiResponse
-
code:数字,例如400
-
message:信息,例如"请求参数没填好"
-
response:抛出异常的类
-
@GetMapping("/detail") @ApiOperation(value = "获取用户详细信息", notes = "传入notice") @ApiResponses(value = { @ApiResponse(code = 500, msg= "INTERNAL_SERVER_ERROR", response = R.class)}) public R<Notice> detail(Integer id) { Notice detail = noticeService.getOne(id); return R.data(detail ); }