背景
最近,栈长发现某些国内的开源项目都使用到了 Knife4j 技术,看名字就觉得很锋利啊!
是不是这样的缩写呢:
Knife4j = Knife for Java ?
Java 匕首?
看起来很牛逼的样子,当然,这是我简单的猜测,从字面上并不能猜到它是干嘛用的!
那么它究竟是一个什么样的框架呢?
Knife4j 简介
Knife4j 的前身是 swagger-bootstrap-ui,其实就是一个纯 Swagger UI 的皮肤项目,用过 Swagger 的应该都知道,Swagger UI 是不怎么好用的,并不太适合国人,所以 swagger-bootstrap-ui 项目就诞生了。
swagger-bootstrap-ui 后面为了满足许多个性化的需求,又加入了许多丰富的服务端特性,不再仅仅只是专注于前端 UI 皮肤了,所以又改名:knife4j。
取名 knife4j 是希望它能像一把匕首一样小巧、轻量,并且功能强悍,更是希望它能成为 Swagger 接口文档服务的通用性增强型解决方案。
Knife4j 由国人程序员萧明于 2017 年开源,到现在已经 4 年多了,看了下 Star 数已经超过 4.7k+ 了:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
Knife4j 还获得了 GVP 项目称号,即 Gitee 最有价值的开源项目,并且我发现现在越来越多的开源项目都在使用它,Swagger UI 可以扔掉了。。
官网地址:
https://doc.xiaominfo.com/knife4j/
开源地址:
https://gitee.com/xiaoym/knife4j
Knife4j 界面赏鉴
Knife4j 采用了 Vue + And Design Vue 组件进行重写,相关界面拿出来供大家赏鉴。
接口文档显示界面:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
接口调试界面:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
Swagger Models 功能:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
编辑切换为居中
添加图片注释,不超过 140 字(可选)
支持导出离线 Markdown、Html:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
编辑切换为居中
添加图片注释,不超过 140 字(可选)
knife4j 果然非常强大,整个界面基于左右菜单式的布局方式,支持多标签同时打开展示、切换,文档和调试也更清晰,感觉更符合国人的操作习惯吧。。
Knife4j 实战
knife4j 目前主要支持以 Java 开发为主,并且支持 Spring MVC、Spring Boot、Spring Cloud 框架的集成使用。
本文栈长就以 Spring Boot 为基础实战下吧:
-
Spring Boot 2.5.0
-
Knife4j 2.0.9
-
Maven 3.6.3
-
JDK 1.8
注意: 使用 Knife4j 2.0.6+ 版本,Spring Boot 的版本要求 2.2.x+
1、Knife4j 依赖引入
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.9</version> </dependency>
2、Knife4j 配置
开启增强功能及基本的登录认证:
knife4j: # 开启增强 enable: true # 开启登录认证 basic: enable: true username: test password: test
支持个性化配置项,如接口地址、接口描述属性、UI 增强等个性化配置功能:
/** * Knife4j 配置类 * 来源微信公众号:Java技术栈 * 作者:栈长 */ @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { @Bean(value = "defaultDocket") public Docket defaultDocket() { // 联系人信息 Contact contact = new Contact("公众号:Java技术栈", "https://www.javastack.cn", "xx@javastack.cn"); // 创建 Docket Docket docket = new Docket(DocumentationType.SWAGGER_2) .apiInfo(new ApiInfoBuilder() .title("Knife4j 测试") .description("Knife4j Test") .termsOfServiceUrl("https://www.javastack.cn") .contact(contact) .version("1.0") .build()) .groupName("1.x") .select() .apis(RequestHandlerSelectors.basePackage("cn.javastack.springboot.knife4j.api")) .paths(PathSelectors.any()) .build(); return docket; } }
Spring Boot 基础就不介绍了,送你一份《Spring Boot 学习笔记》,高清理论+实战版,照着学习,没有不会的,最新版正在努力更新中,可以持续关注公众号 Java技术栈,会第一时间分享给大家。
3、新增测试接口
新增两个测试接口,一个登录(POST),一个问好(GET)。
/** * Knife4j 测试接口 * 来源微信公众号:Java技术栈 * 作者:栈长 */ @Api(tags = "测试模块") @RestController public class Knife4jController { /** * Knife4j 测试接口问好 * 来源微信公众号:Java技术栈 * 作者:栈长 */ @ApiImplicitParam(name = "name", value = "名称", required = true) @ApiOperation(value = "公众号Java技术栈向你问好!") @ApiOperationSupport(order = 2, author = "栈长") @GetMapping("/knife4j/hi") public ResponseEntity<String> hello(@RequestParam(value = "name") String name) { return ResponseEntity.ok("Hi:" + name); } /** * Knife4j 测试接口登录 * 来源微信公众号:Java技术栈 * 作者:栈长 */ @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "用户名", required = true), @ApiImplicitParam(name = "password", value = "密码", required = true) }) @ApiOperation(value = "接口登录!") @ApiOperationSupport(order = 1, author = "栈长") @PostMapping("/knife4j/login") public ResponseEntity<String> login(@RequestParam(value = "username") String username, @RequestParam(value = "password") String password) { if (StringUtils.isNotBlank(username) && "javastack".equals(password)) { return ResponseEntity.ok("登录成功:" + username); } return ResponseEntity.ok("用户名或者密码有误:" + username); } }
上面为了支持接口顺序和接口作者,使用了 Knife4j 的@ApiOperationSupport 注解,其他的均为 Swagger 自带的注解,从该目录下看还支持下面的注解:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
更多可去官网进行学习。
完整的 Demo 代码就不一一帖了,本节教程所有实战源码已上传到这个仓库:
https://github.com/javastacks/spring-boot-best-practice
4、Knife4j 测试
启动应用,打开 Knife4j 文档页:
http://localhost:8080/doc.html
编辑切换为居中
添加图片注释,不超过 140 字(可选)
登录认证
编辑切换为居中
添加图片注释,不超过 140 字(可选)
主页信息
主页会显示一些已经配置好的文档参数及接口统计信息,并且在首页模块菜单中也看到了我们的测试模块的两个接口。
接口文档:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
登录接口文档
编辑切换为居中
添加图片注释,不超过 140 字(可选)
问好接口文档
调试一下:
编辑切换为居中
添加图片注释,不超过 140 字(可选)
登录失败
编辑切换为居中
添加图片注释,不超过 140 字(可选)
登录成功
编辑切换为居中
添加图片注释,不超过 140 字(可选)
问好成功
这里栈长使用了接口排序、还有接口作者功能,另外还支持分组排序、自定义文档、Swagger 资源保护、导出 Markdown、参数缓存等众多强大功能,增强功能多达 29 项,有兴趣的可以自行尝试...
总结
好了,今天栈长给大家介绍了国人程序员开源的一款 Knife4j 项目,也就是 Swagger 的增强版,毫无疑问要比 Swagger UI 更强大,更好用,也符合国人的习惯!
如果你也在使用 Swagger,可以考虑使用 Knife4j,它不仅有更强大的 UI,更有多达 29 项的增强功能,它们并不是替代关系,就像 Mybatis Plus 和 Mybatis 的关系一样,它能助你更进一步提高开发生产力。
如果你也在使用 Knife4j,欢迎留言分享哦!
本节教程所有实战源码已上传到这个仓库:
https://github.com/javastacks/spring-boot-best-practice
资源获取:
大家点赞、收藏、关注、评论啦 、查看👇🏻👇🏻👇🏻微信公众号获取联系方式👇🏻👇🏻👇🏻
精彩专栏推荐订阅:在下方专栏👇🏻👇🏻👇🏻👇🏻