作为一个开发人员最怕的就是写文档了,但是要想成为一个合格的程序员,写好文档也是一个必备的技能。开发中我们经常要写接口服务,既然是服务就要跟别人对接,那难免要写接口文档,那么如何”优雅“的写接口文档呢?本文介绍一个在写代码的过程就可以写完接口文档的工具——Swagger2(江湖人称丝袜哥😂)
下文基于 SpringBoot + Maven 介绍 Swagger2 的使用
加入依赖
1 |
|
编写Swagger全局配置
1 |
|
Controller 编写
- 类上面增加
@Api
注解
1 |
|
- 方法上增加
@ApiOperation
注解
1 |
|
- 方法参数 Model 属性自定义设置
1 |
|
@ApiModel注解用在 model 类上 @ApiModelProperty 用于 model 的属性上
- 可以定义是否 required, example, hidden, value, name等参数
- hidden 为 true 在页面上就不会显示在字段
界面使用
-
启动项目,打开项目文档地址:http://ip:port/swagger-ui.html
-
如图显示的内容。还可以添加 header 参数,以及在网页上进行测试。
增加密码
- 接口文档我们往往需要让有权限的人查看,所以我们可以根据 Spring-Security增加账号密码管理。
- 增加依赖
1 |
|
- 配置文件中增加账号密码配置
1 |
|
- 增加了依赖和账号密码后重启项目,再次打开文档地址就要去输入账号和密码了
输入对应的账号和密码就可以登录了。
小坑
- 如果在启动的时候出现如下错误,是因为新版的 Swagger2需要高版本的 guava
1 |
|
- 解决方案增加如下配置即可
1 |
|
- Security 过滤特定路径
- 针对非文档路径的其他路径,我们需要进行过滤,采用如下方式。
1 |
|
小结
Swagger2 让开发人员在编写代码的时候就完成了接口文档,方便快捷。而且随项目一起部署,不用担心丢失,需要的时候只要打开项目地址就可以了,十分方便。
在使用 Swagger2写完接口文档后,还可以直接导出 JSON 文件,访问路径http://ip:port/v2/api-docs
可以看到JSON 文档。生成的 JSON 文档可以配合 YAPI 或者 POSTMAN 使用都是可以的。