Swagger文档的使用

matevip 2021-6-3 大约 4 分钟

# 一、Swagger简介

由于架构革新，进入了前后端分离，服务端只需提供RESTful API的时代。
而构建RESTful API会考虑到多终端的问题，这样就需要面对多个开发人员甚至多个开发团队。
为了减少与其他团队对接的沟通成本，我们通常会写好对应的API接口文档。
从最早开始的word文档，到后续的showdoc，都能减少很多沟通成本，但随之带来的问题也比较麻烦。在开发期间接口会因业务的变更频繁而变动，如果需要实时更新接口文档，这是一个费时费力的工作。
为了解决上面的问题，Swagger应运而生。他可以轻松的整合进框架，并通过一系列注解生成强大的API文档。他既可以减轻编写文档的工作量，也可以保证文档的实时更新，将维护文档与修改代码融为一体，是目前较好的解决方案。

# 二、平台集成

# 2.1 knife4j

商业版集成了knife4j (opens new window)的方案，界面更加美观。

只要项目中引入mate-starter-web，swagger就默认集成。

# 2.2 演示样例

https://plus-api.mate.vip/doc.html (opens new window)

# 三、常用注解

@Api()用于类；表示标识这个类是swagger的资源
@ApiOperation()用于方法；表示一个http请求的操作
@ApiParam()用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
@ApiModel()用于类表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()用于方法，字段表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类，方法，方法参数表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

# 四、代码示例

@Api

@Api(value = "用户博客", tags = "博客接口")
public class NoticeController {

}

1
2
3
4

@ApiOperation

@GetMapping("/detail")
@ApiOperation(value = "获取用户详细信息", notes = "传入notice")
public Result<Notice> detail(Integer id) {
   Notice detail = noticeService.getOne(id);
   return Result.data(detail );
}

1
2
3
4
5
6

@ApiResponses

@GetMapping("/detail")
@ApiOperation(value = "获取用户详细信息", notes = "传入notice")
@ApiResponses(value = {@ApiResponse(code = 500, msg= "INTERNAL_SERVER_ERROR", response = R.class)})
public Result<Notice> detail(Integer id) {
   Notice detail = noticeService.getOne(id);
   return Result.data(detail );
}

1
2
3
4
5
6
7

@ApiImplicitParams

@GetMapping("/list")
@ApiImplicitParams({
   @ApiImplicitParam(name = "category", value = "公告类型", paramType = "query", dataType = "integer"),
   @ApiImplicitParam(name = "title", value = "公告标题", paramType = "query", dataType = "string")
})
@ApiOperation(value = "分页", notes = "传入notice")
public Result<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 Result.data(pages );
}

1
2
3
4
5
6
7
8
9
10

@ApiParam

@PostMapping("/remove")
@ApiOperation(value = "逻辑删除", notes = "传入notice")
public Result remove(@ApiParam(value = "主键集合") @RequestParam String ids) {
   boolean temp = noticeService.deleteLogic(Func.toIntList(ids));
   return Result.status(temp);
}

1
2
3
4
5
6

@ApiModel 与 @ApiModelProperty

@Data
@ApiModel(value = "MateUser ", description = "用户对象")
public class MateUser implements Serializable {

   private static final long serialVersionUID = 1L;

   @ApiModelProperty(value = "主键", hidden = true)
   private Integer userId;

   @ApiModelProperty(value = "昵称")
   private String userName;

   @ApiModelProperty(value = "账号")
   private String account;

   @ApiModelProperty(value = "角色id")
   private String roleId;
 
   @ApiModelProperty(value = "角色名")
   private String roleName;

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

@ApiIgnore()

@ApiIgnore()
@GetMapping("/detail")
public Result<Notice> detail(Integer id) {
   Notice detail = noticeService.getOne(id);
   return Result.data(detail );
}

1
2
3
4
5
6

# 四、全局配置

# 4.1 mate-starter-web模块集成

参见 mate-starter-web/src/main/resources/mate-swagger.yml

mate:
  swagger:
    enable: false
    title: MateCLoud Plus文档管理中心
    description: MateCLoud Plus文档管理
    license: Powered by MateCloud Plus
    service-url: http://doc.mate.vip
    contact-name: pangu
    contact-url: https://www.mate.vip
    contact-email: 7333791@qq.com
# knife4j配置
knife4j:
  enable: ${mate.swagger.enable}
  # 开启生产环境屏蔽
  production: false
  basic:
    enable: true
    username: admin
    password: matecloud
  setting:
    # 是否不显示Knife4j默认的footer，默认为true(显示)
    enableFooter: false
    # 是否自定义Footer，默认为false(非自定义)
    enableFooterCustom: true
    # 自定义Footer内容,支持Markdown语法
    footerCustomContent: Apache License 2.0 | Copyright 2020-[MateCloud Plus](http://doc.mate.vip)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 4.2 自定义主页内容

参见文档：https://xiaoym.gitee.io/knife4j/documentation/customHome.html (opens new window)

knife4j:
  enable: true
  setting:
    enableHomeCustom: true
    homeCustomLocation: classpath:markdown/home.md

1
2
3
4
5

# 五、注意点

本项目设置了开关，也可以对swagger进行开启和关闭

  # Swagger文档开关
  swagger:
    enable: true

1
2
3

目前knife4j版本刷新后会丢失增强配置，所以需要手动关闭tab，再重新打开文档页面才会生效。
因为在生产环境暴露接口会非常危险

# 六、结束语

本文讲述了聚合文档的实现以及Swagger接口描述的润色，想知道更多用法，还需查看官方文档。

swagger文档直达：https://swagger.io/ (opens new window)
swagger-bootstrap-ui文档直达：https://doc.xiaominfo.com/guide/ (opens new window)

Feign的封装和使用大话数据库

Swagger文档的使用

# 一、Swagger简介

# 二、平台集成

# 2.1 knife4j

# 2.2 演示样例

# 三、常用注解

# 四、代码示例

# 四、全局配置

# 4.1 mate-starter-web模块集成

# 4.2 自定义主页内容

# 五、注意点

# 六、结束语

详情