SpringBoot2与Swagger(knife4j)的最新版本整合（带认证）_knife4j开启身份认证

前言

现项目中我们常常直接用Swagger来让项目展示接口文档体验，随着项目后续的发展，大家对Swagger对原生的界面不是很满意，于是就出现了一个新的Swagger扩展项目，叫swagger-bootstrap-ui，swagger-bootstrap-ui是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，能拥有一份简洁、强大的接口文档体验。
作者对swagger-bootstrap-ui不断的迭代，在1.9.6的版本时，作者把swagger-bootstrap-ui项目重命名为Knife4j，目标是希望它能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端。

文档可参考：

• 说明文档： https://doc.xiaominfo.com
• 效果(旧版)：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
• 效果(2.X版)：http://knife4j.xiaominfo.com/doc.html
• Gitee：https://gitee.com/xiaoym/knife4j
• GitHub：https://github.com/xiaoymin/swagger-bootstrap-ui
• 示例：https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

核心功能

该UI增强包主要包括两大核心功能：文档说明 和 在线调试

• 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。
• 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简洁、强大。

环境

• 开发工具：SpringToolSuite4
• 配置工具：Maven
• 其它版本：Spring Boot 2.x + Jdk1.8+knife4j2.0.6

项目目录

包引入配置

本文用的是Springboot2的版本

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.3.RELEASE</version>
		<relativePath /> <!-- lookup parent from repository -->
	</parent>
	<dependency>
		    <groupId>com.github.xiaoymin</groupId>
		    <artifactId>knife4j-spring-boot-starter</artifactId>
		    <version>2.0.6</version>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>
		<dependency>
			<groupId>com.google.guava</groupId>
			<artifactId>guava</artifactId>
			<version>20.0</version>
			<scope>compile</scope>
		</dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

注意：只需要引入knife4j-spring-boot-starter即可，它会把其它的依赖都加载进来，如要Swagger的核心包也会加载进来
我们看下他的依赖包，

配置文件

server:
  port: 8089
#配置swagger配置
knife4j:
  basic: 
    username: admin
    password: 123
    enable: true #开启认证
  production: false #默认是false ,屏蔽所有Swagger的相关资源
  enable: true #是否开启swagger

1
2
3
4
5
6
7
8
9
10
11

源代码

SwaggerConfiguration

@Configuration
@EnableSwagger2WebMvc
@EnableKnife4j
@ConditionalOnExpression("${knife4j.enable}") //开启访问接口文档的权限  **knife4j.enable是在yml配置文件中配置为true**
public class SwaggerConfiguration {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.bitter.controller")).paths(PathSelectors.any()).build();
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs(带认证）")
				.description("更多Spring Boot相关文章请关注：https://blog.csdn.net/elvishehai")
				.termsOfServiceUrl("https://blog.csdn.net/elvishehai").version("1.0").build();
	}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@EnableSwagger2WebMvc原先是用@EnableSwagger2来做注解的，最新版本直接使用@EnableSwagger2WebMvc来做注解，暂时可以把他理解为功能就是一样的
@EnableKnife4j API接口文档的开关

Controller

@RestController
@Api(tags = "Swagger")
public class BitterController {

	@ApiOperation(value = "hello", notes = "")
	@GetMapping("hello")
	public String hello() {
		return "hello world";
	}
}
1
2
3
4
5
6
7
8
9
10

运行结果

输入用户名和密码才可以访问接口

输入用户和密码后admin/123

测试接口,返回接口定义的数据，测试成功

源码位置

gitee下见springboot-swagger-auth

总结

以上是简单的SpringBoot2与Swagger(knife4j)的最新版本整合，只是为了测试该版本的功能使用，同时有了该认证的功能后，许多的漏洞工具也无法扫描出漏洞，对系统来说更安全。不过对于部署系统到生产系统,为了接口安全,可以屏蔽所有Swagger的相关资源，在配置文件中配置production: true就可以。
欢迎有问题及时交流~
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多交流。