章
目
录
上一节我们了解了Swagger简介，知道了Swagger是干什么的有什么作用，接下来我们一起看下Springboot如何集成Swagger2。
1、Springfox概述
Springfox是一个基于Spring的组件，它是基于Swagger的发展而来的全新项目。Springfox的主要优势在于它能够根据代码自动生成接口文档，而不需要手动修改描述文件（如YAML或JSON）。这使得在频繁更新项目版本时，开发人员只需修改代码，而不必费心更新描述文件，从而保持接口文档的实时性。
Springfox利用Spring的AOP（面向切面编程）特性将Swagger集成进来，底层仍然使用Swagger，但使用起来更加方便。因此，在实际开发中，许多开发团队倾向于直接使用Springfox，以简化接口文档的维护和更新工作。这种方式有助于确保接口文档与实际代码的一致性，同时减轻了开发人员的工作负担。
2、Springboot集成Swagger2步骤演示
1、创建SpringBoot项目
如何创建SpringBoot项目，这里就不再详细说明，如果不会，请参考：《SpringBoot教程：创建Hello World应用程序》
2、导入swagger依赖
在pom.xml中导入swagger依赖，这里我们使用swagger2版本，需要导入两个依赖包，如下：
<!--swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。
3、编写配置文件
在配置文件 config 目录下，添加 swagger 的配置文件 Swagger2Config.java
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class Swagger2Config {
}
这个时候 Swagger 已经算是整合到项目之中了，可以启动SpringBoot项目，浏览器输入：http://localhost:8080/swagger-ui.html （这里的端口与你Springboot中yml配置文件中保持一致，一般默认是8080）即可查看 swagger 文档，如下：
可以看到 Swagger 文档中大概有这四类信息
- 组
- 基本信息
- 接口信息
- 实体类信息
4. 配置基本信息
Swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息的设置在 ApiInfo 这个对象中。
Swagger 默认的基本信息展示：
ApiInfo 中默认的基本设置如下：
- title：Api Documentation
- description：Api Documentation
- version：1.0
- termsOfServiceUrl：urn:tos
- contact：无
- license：Apache 2.0
- licenseUrl：http://www.apache.org/licenses/LICENSE-2.0
Swagger2Config.java 配置文件添加以下内容：
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
// 配置基本信息
.apiInfo(apiInfo());
}
/**
* 基本信息设置
*/
private ApiInfo apiInfo() {
Contact contact = new Contact(
"潘子夜", // 作者姓名
"https://www.panziye.com", // 作者网址
"xxxxblog@126.com"); // 作者邮箱
return new ApiInfoBuilder()
.title("潘子夜博客-接口文档") // 标题
.description("专注分享编程技术") // 描述
.termsOfServiceUrl("https://hao.panziye.com") // 跳转连接
.version("1.0") // 版本
.license("Swagger教程")
.licenseUrl("https://www.panziye.com/back/9777.html")
.contact(contact)
.build();
}
注意：这里的Contact类是springfox下的：
import springfox.documentation.service.Contact;
重启项目，再次访问swagger文档页，发现就变成我们刚刚设置的了：
5、配置接口信息
默认情况下，Swagger 是会展示所有的接口信息的（点击basic-error-controller即可展开），包括最基础的 basic-error 相关的接口
有时候我们希望不要展示 basic-error-controller 相关的接口，或者是说这想要显示某些接口，比如说：user-controller 下的接口，由该怎么去实现呢？这个时候就需要设置 扫描接口
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
//.any() // 扫描全部的接口，默认
//.none() // 全部不扫描
.basePackage("com.test.springbootdemo.controller") // 扫描指定包下的接口，最为常用
//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
//.ant("/user/**") // 满足字符串表达式路径
//.regex("") // 符合正则的路径
)
.build();
}
controller包下新增Usercontroller类：
@Controller
@RequestMapping("/user")
public class UserController {
@PostMapping("/query-user-info")
public void queryUserInfo(){
}
}
重启再次访问效果如下：
可以看到之前 basic-error-controller 相关的接口已经没有了，这里要求你的controller下有接口文件，否则直接显示“No operations defined in spec!”
6、 配置分组信息
Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 default `分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。
swagger 文档中组名默认是 default，可通过 .groupName(String )
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.groupName("panziye"); // 修改组名为 "panziye"
}
如果需要配置多个组的话，就需要配置多个 docket() 方法，这里我就简单写两组，代码如下：
/**
* 展示 controller 包下所有的接口
*/
@Bean
public Docket docket1() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.groupName("panziye") // 修改组名为 "mike"
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
.basePackage("com.test.springbootdemo.controller") // 扫描指定包下的接口，最为常用
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
)
.build();
}
/**
* 展示路径为 /error 的所有接口（基础接口）
*/
@Bean
public Docket docket2() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.groupName("hao") // 修改组名为 "hao"
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
.any() // 扫描全部的接口，默认
)
.paths(PathSelectors
.ant("/error") // 满足字符串表达式路径
)
.build();
}
重启服务，打开 Swagger 文档，接口信息改变如下所示：
组名为 panziye 的文档中只有 user-controller 相关的接口信息，组名为 hao 的文档中只有 basic-error-controller 相关的接口信息
6、控制 Swagger 在不同环境的开启与关闭
在开发或者测试环境下，我们开启 swagger 会方便前端和后端的交互，但是如果在生产环境下也开启 swagger 的话，是会将接口暴露出去的，有极大风险，如何让 swagger 根据不同的环境来决定是否开启？
这里我准备了四个项目的配置文件，dev、test、pro 三个环境的配置文件仅是端口上的不同
- application.yml ————– 全局配置文件
- application-dev.yml ——— 开发环境配置文件
- application-test.yml ——– 测试环境配置文件
- application-pro.yml ——– 生产环境配置文件
application.yml 内容如下，用于指定选择的环境：
spring:
profiles:
active: dev
可以通过代码判断此时是在什么环境：dev、test、pro，如果是在 pro 生产环境，则关闭 swagger。
/**
* swagger 配置
* @param environment 环境
*/
@Bean
public Docket docket(Environment environment) {
// 设置环境范围
Profiles profiles = Profiles.of("dev","test");
// 如果在该环境返回内则返回：true，反之返回 false
boolean flag = environment.acceptsProfiles(profiles);
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.enable(flag); // 是否开启 swagger：true -> 开启，false -> 关闭
}
在 application.yml 全局配置文件中环境指向 dev 时，是可以打开 swagger 的，如果我将 application.yml 全局配置文件中环境指向 pro 时，就不能打开 swagger 了，提示 Could not render e, see the console 。
以上就是Springboot集成Swagger2的全部内容，希望对你有帮助。
