Swagger2的使用-集成至SpringBoot
前言
作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。
一、简介
官网：https://swagger.io/
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势
- 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
- 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
二、基本使用
1. 导入相关依赖
通过在项目中引入
Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.7之前版本与2.8之后版本 在ui风格上有较大差异
2. 编写配置文件
在配置文件
config目录下，添加 swagger 的配置文件SwaggerConfig.java
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}
@EnableSwagger2是springfox提供的一个注解，代表swagger2相关技术开启。会扫描当前类所在包，及子包中所有类型的swagger相关注解，做swagger文档的定制
这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入：http://localhost:8201/swagger-ui.html#/ （这里我的项目端口是 8201 ，所以我打开的文档地址为 http://localhost:8201/swagger-ui.html# ）即可查看 swagger 文档。
可以看到 Swagger 文档中大概有这四类信息
- 分组信息
- 基本信息
- 接口信息
- 实体类信息
2.1 配置基本信息
Swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息的设置在 ApiInfo 这个对象中。
ApiInfo 中默认的基本设置
- title： //接口标题
- description： //接口文档标题说明
- version： //版本
- termsOfServiceUrl： //网站地址
- contact： //Contact类型，包含作者name，网址，邮箱
- license：//协议
- licenseUrl： //协议链接
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 配置基本信息
.build();
}
// 基本信息设置
private ApiInfo apiInfo() {
Contact contact = new Contact(
"米大傻", // 作者姓名
"https://blog.csdn.net/xhmico?type=blog", // 作者网址
"777777777@163.com"); // 作者邮箱
return new ApiInfoBuilder()
.title("多加辣-接口文档") // 标题
.description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
.termsOfServiceUrl("https://www.baidu.com") // 跳转连接
.version("1.0") // 版本
.license("Swagger-的使用(详细教程)")
.licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535")
.contact(contact)
.build();
}
2.2配置分组信息
Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在
default分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.groupName("***") // 修改组名为 " ***"
// 配置基本信息
.apiInfo(apiInfo())
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
.basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
//.any() // 扫描全部的接口，默认
//.none() // 全部不扫描
//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
//.ant("/user/**") // 满足字符串表达式路径
//.regex("") // 符合正则的路径
)
.build();
}
如果需要配置多个组的话，就需要配置多个 docket() 方法，这里我就简单写两组，代码如下：
/**
* 展示 controller 包下所有的接口
*/
@Bean
public Docket docket1() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.groupName("mike") // 修改组名为 "mike"
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
.basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
)
.build();
}
/**
* 展示路径为 /error 的所有接口（基础接口）
*/
@Bean
public Docket docket2() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.groupName("yank") // 修改组名为 "yank"
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
.any() // 扫描全部的接口，默认
)
.paths(PathSelectors
.ant("/error") // 满足字符串表达式路径
)
.build();
}
3.常见注解、配置接口信息
@ApiModel(POJO类说明)
该注解是作用于类上面的，是用来描述类的一些基本信息的。
- value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
- description：对于类，提供一个详细的描述信息
- parent：这个属性用于描述的是类的一些父类信息
- discriminator：这个属性解释起来比较麻烦，因为这个类主要体现在断言当中
- subTypes：可以通过这个属性，指定我们想要使用的子类
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "Id请求体")
public class IdReq {
private String id;
}
@ApiModelProperty（POJO类属性说明）
它的作用是添加和操作属性模块的数据。详情：@ApiModelProperty注解的用法
- value: 参数类型为String，作用为此属性的简要描述。
- notes: 参数类型为String，作用为该字段的注释说明。
- example: 参数为String类型，作用为属性的示例值。
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "Id请求体")
public class IdReq {
@ApiModelProperty("主键id")
private String id;
}
@Api(接口类说明)
该注解使用在接口Controller上，描述整个Controller的一些信息
- tags： Controller类描述
@Api(tags="订单模块")
@Controller
public class OrderController {
}
@ApiOperation(方法说明)
用在请求的方法上，说明方法的作用
- value:说明方法的作用
- notes:方法的备注说明
@PostMapping(value = "/query-user-info")
@ApiOperation(value = "根据id查询用户详情")
public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) {
return ResponseBean.success(userService.queryUserInfo(req));
}
@ApiParam(方法参数说明)
- name：参数名
- value：参数说明
- required：是否必填
@PostMapping(value = "/query-user-infos")
@ApiOperation(value = "条件查询用户信息")
public ResponseBean queryUserInfos(
// name 用户名称 不必填
@ApiParam(value = "用户名称", required = false) @RequestParam(required = false) String name,
// gender 用户性别 必填
@ApiParam(value = "用户性别", required = true) @RequestParam(required = true) GenderEnum gender
) {
return ResponseBean.success(userService.queryUserInfos(name,gender));
}
三、启动
启动 SpringBoot 应用,访问 http://localhost:8080/swagger-ui.html
扫一扫
635
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
