再见Swagger UI 国人开源了一款超好用的 API 文档生成框架,真香

简介: 背景最近,栈长发现某些国内的开源项目都使用到了 Knife4j 技术,看名字就觉得很锋利啊!是不是这样的缩写呢:Knife4j = Knife for Java ?Java 匕首?看起来很牛逼的样子,当然,这是我简单的猜测,从字面上并不能猜到它是干嘛用的!那么它究竟是一个什么样的框架呢?

背景

最近,栈长发现某些国内的开源项目都使用到了 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+ 了:

网络异常,图片无法展示
|

Knife4j 还获得了 GVP 项目称号,即 Gitee 最有价值的开源项目,并且我发现现在越来越多的开源项目都在使用它,Swagger UI 可以扔掉了。。

官网地址:

https://doc.xiaominfo.com/knife4j/

开源地址:

https://gitee.com/xiaoym/knife4j

Knife4j 界面赏鉴

Knife4j 采用了 Vue + And Design Vue 组件进行重写,相关界面拿出来供大家赏鉴。

接口文档显示界面:

网络异常,图片无法展示
|

接口调试界面:

网络异常,图片无法展示
|

Swagger Models 功能:

网络异常,图片无法展示
|

网络异常,图片无法展示
|

支持导出离线 Markdown、Html:

网络异常,图片无法展示
|

网络异常,图片无法展示
|

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 自带的注解,从该目录下看还支持下面的注解:

网络异常,图片无法展示
|

更多可去官网进行学习。

完整的 Demo 代码就不一一帖了,本节教程所有实战源码已上传到这个仓库:

https://github.com/javastacks/spring-boot-best-practice

4、Knife4j 测试

启动应用,打开 Knife4j 文档页:

http://localhost:8080/doc.html

网络异常,图片无法展示
|

登录认证

网络异常,图片无法展示
|

主页信息

主页会显示一些已经配置好的文档参数及接口统计信息,并且在首页模块菜单中也看到了我们的测试模块的两个接口。

接口文档:

网络异常,图片无法展示
|

登录接口文档

网络异常,图片无法展示
|

问好接口文档

调试一下:

网络异常,图片无法展示
|

登录失败

网络异常,图片无法展示
|

登录成功

网络异常,图片无法展示
|

问好成功

这里栈长使用了接口排序、还有接口作者功能,另外还支持分组排序、自定义文档、Swagger 资源保护、导出 Markdown、参数缓存等众多强大功能,增强功能多达 29 项,有兴趣的可以自行尝试...

总结

好了,今天栈长给大家介绍了国人程序员开源的一款 Knife4j 项目,也就是 Swagger 的增强版,毫无疑问要比 Swagger UI 更强大,更好用,也符合国人的习惯!

如果你也在使用 Swagger,可以考虑使用 Knife4j,它不仅有更强大的 UI,更有多达 29 项的增强功能,它们并不是替代关系,就像 Mybatis Plus 和 Mybatis 的关系一样,它能助你更进一步提高开发生产力。

如果你也在使用 Knife4j,欢迎留言分享哦!

本节教程所有实战源码已上传到这个仓库:

https://github.com/javastacks/spring-boot-best-practice

相关文章
|
27天前
|
人工智能 自然语言处理 API
百聆:集成Deepseek API及语音技术的开源AI语音对话助手,实时交互延迟低至800ms
百聆是一款开源的AI语音对话助手,结合ASR、VAD、LLM和TTS技术,提供低延迟、高质量的语音对话体验,适用于边缘设备和低资源环境。
671 4
百聆:集成Deepseek API及语音技术的开源AI语音对话助手,实时交互延迟低至800ms
|
1月前
|
API 开发者
通义灵码 API 开发文档自动生成场景DEMO
通义灵码API开发文档自动生成场景DEMO展示了通过自定义指令,大模型能快速根据类代码生成Markdown格式的API文档。文档详细描述API的入参、出参,并可生成测试代码等示例,帮助开发者快速创建美观的API文档。
|
1月前
|
开发框架 数据可视化 .NET
.NET 中管理 Web API 文档的两种方式
.NET 中管理 Web API 文档的两种方式
43 14
|
1月前
|
人工智能 前端开发 API
Gemini Coder:基于 Google Gemini API 的开源 Web 应用生成工具,支持实时编辑和预览
Gemini Coder 是一款基于 Google Gemini API 的 AI 应用生成工具,支持通过文本描述快速生成代码,并提供实时代码编辑和预览功能,简化开发流程。
143 38
Gemini Coder:基于 Google Gemini API 的开源 Web 应用生成工具,支持实时编辑和预览
|
1月前
|
人工智能 JSON 安全
DeepSeek Engineer:集成 DeepSeek API 的开源 AI 编程助手,支持文件读取、编辑并生成结构化响应
DeepSeek Engineer 是一款开源AI编程助手,通过命令行界面处理用户对话并生成结构化JSON,支持文件操作和代码生成。
757 6
DeepSeek Engineer:集成 DeepSeek API 的开源 AI 编程助手,支持文件读取、编辑并生成结构化响应
|
2月前
|
存储 人工智能 API
AgentScope:阿里开源多智能体低代码开发平台,支持一键导出源码、多种模型API和本地模型部署
AgentScope是阿里巴巴集团开源的多智能体开发平台,旨在帮助开发者轻松构建和部署多智能体应用。该平台提供分布式支持,内置多种模型API和本地模型部署选项,支持多模态数据处理。
396 4
AgentScope:阿里开源多智能体低代码开发平台,支持一键导出源码、多种模型API和本地模型部署
|
3月前
|
缓存 API 数据库
Python哪个框架合适开发速卖通商品详情api?
在跨境电商平台速卖通的商品详情数据获取与整合中,Python 语言及其多种框架(如 Flask、Django、Tornado 和 FastAPI)提供了高效解决方案。Flask 简洁灵活,适合快速开发;Django 功能全面,适用于大型项目;Tornado 性能卓越,擅长处理高并发;FastAPI 结合类型提示和异步编程,开发体验优秀。选择合适的框架需综合考虑项目规模、性能要求和团队技术栈。
44 2
|
3月前
|
Web App开发 人工智能 自然语言处理
WebChat:开源的网页内容增强问答 AI 助手,基于 Chrome 扩展的最佳实践开发,支持自定义 API 和本地大模型
WebChat 是一个基于 Chrome 扩展开发的 AI 助手,能够帮助用户理解和分析当前网页的内容,支持自定义 API 和本地大模型。
302 0
|
3月前
|
安全 API 数据库
Python哪个框架合适开发淘宝商品详情api?
在数字化商业时代,开发淘宝商品详情API成为企业拓展业务的重要手段。Python凭借其强大的框架支持,如Flask、Django、Tornado和FastAPI,为API开发提供了多样化的选择。本文探讨了这些框架的特点、优势及应用场景,帮助开发者根据项目需求选择最合适的工具,确保API的高效、稳定与可扩展性。
43 0
|
3月前
|
开发框架 Java 关系型数据库
Java哪个框架适合开发API接口?
在快速发展的软件开发领域,API接口连接了不同的系统和服务。Java作为成熟的编程语言,其生态系统中出现了许多API开发框架。Magic-API因其独特优势和强大功能,成为Java开发者优选的API开发框架。本文将从核心优势、实际应用价值及未来展望等方面,深入探讨Magic-API为何值得选择。
132 2

热门文章

最新文章