Knife4j
前身是swagger-bootstrap-ui
,是一个为Swagger接口文档赋能的工具
文档:https://xiaoym.gitee.io/knife4j/(opens new window)
效果(旧版):http://swagger-bootstrap-ui.xiaominfo.com/doc.html(opens new window)
效果(2.X版):http://knife4j.xiaominfo.com/doc.html(opens new window)
Gitee:https://gitee.com/xiaoym/knife4j(opens new window)
GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui(opens new window)
示例:https://gitee.com/xiaoym/swagger-bootstrap-ui-demo(opens new window)
1、构建响应curl时,去除Knife4j自定义添加的部分Header头
2、增加自定义主页的增强配置,开发者可以提供一个Markdown文档,用来自定义Home主页显示的内容Gitee #I24ZXI(opens new window)
knife4j:
enable: true
setting:
# 是否自定义显示Home主页,默认为false
enableHomeCustom: true
# 自定义主页Home的markdown文档路径,只能设置1个,如果设置为目录,则默认取第一个
homeCustomLocation: classpath:markdown/home.md
3、OpenAPI开放接口可以通过增强配置是否显示Gitee #I25273(opens new window)
knife4j:
enable: true
setting:
# 是否显示文档中的Open标签栏,默认为true
enableOpenApi: false
4、搜索框可以通过增强配置是否显示Gitee #I24ZYY(opens new window)
knife4j:
enable: true
setting:
# 是否显示文档中的搜索框,默认为true,即显示
enableSearch: false
5、文档最下边的footerkey通过增强配置是否显示,并且可以自定义显示内容Gitee #I24ZYD(opens new window)
knife4j:
enable: true
setting:
# 是否不显示Knife4j默认的footer,默认为true(显示)
enableFooter: false
# 是否自定义Footer,默认为false(非自定义)
enableFooterCustom: true
# 自定义Footer内容,支持Markdown语法
footerCustomContent: 中国XXX科技股份有限公司版权所有
6、废弃springfox中的控制参数接口/swagger-resources/configuration/ui
,针对是否开启Debug调试,通过Knife4j提供的个性化增强配置进行控制
knife4j:
enable: true
setting:
# 是否显示调试Tab框架,默认为true(显示)
enableDebug: false
7、解决微服务架构下,丢失basePath的问题Gitee #I23NWM (opens new window)、Gitee #I23N6L (opens new window)、Gitee #I25ZTC (opens new window)、GitHub #286(opens new window)
8、自定义文档以及自定义Home主页的Markdown支持Html语法Gitee #I24ZZA(opens new window)
9、去除文档右上角?号的文档显示Gitee #I24ZYL(opens new window)
10、增强配置增加开启动态请求参数配置的配置Gitee #I24EBO(opens new window)
knife4j:
enable: true
setting:
# 开启动态请求参数调试,默认为false(不开启)
enableDynamicParameter: true
11、如果当前服务只有一个分组的情况下,开发者可以通过配置enableGroup
项来控制界面的分组显示Gitee #I25MQG (opens new window),配置如下:
knife4j:
enable: true
setting:
# Ui界面不显示分组元素
enableGroup: false
最终效果图如下:
12、基础类型的请求参数与响应参数示例显示优化Gitee #I24YKT(opens new window)
13、@ApiOperationSupport
和@DynamicParameters
注解不能同时使用的问题Gitee #I24JWV(opens new window)
14、解决V3版本中starter存在冲突的问题Gitee #I2420J(opens new window)
15、优化markdown渲染的组件方式。
16、离线文档导出移除导出PDF项,导出pdf功能不管是基于markdown或者是word都能轻松实现,因此Knife4j废弃此功能
17、OpenAPI3结构中支持表单类型中scheme解析显示为jsonGitee #I24PCZ(opens new window)
18、针对Authorize标志的接口,添加锁的icon在接口中进行体现Gitee #I23W0S (opens new window)
19、增强配置本地缓存更新策略
20、针对禁用文档管理菜单项后,同步禁用右上角个性化菜单的显示。Gitee #I262VN
21、请求OpenAPI规范实例接口默认发送一个language
的header,如果服务端做了i18n的配置可以根据此header动态返回不同的语言释义。
21、解决根据路径设置界面i18n显示时,和服务端增强配置冲突的问题,如果开发者通过url路径来设置界面的i18n显示,则默认以路径中的为准,否则,取后端增强配置的language
22、菜单收缩时显示存在异常的问题Gitee #I2646F(opens new window)
23、OpenAPI3规范适配支持JSR303支持GitHub #283(opens new window)
24、请求参数的数据类型为空的情况下优化,显示默认值string
Java开发使用Knife4j
目前有一些不同的版本变化,主要如下:
1、如果开发者继续使用OpenAPI2的规范结构,底层框架依赖springfox2.10.5版本,那么可以考虑Knife4j
的2.x版本
com.github.xiaoymin
knife4j-spring-boot-starter
2.0.8
2、如果开发者使用OpenAPI3的结构,底层框架依赖springfox3.0.0,可以考虑Knife4j
的3.x版本
com.github.xiaoymin
knife4j-spring-boot-starter
3.0.2
3、如果开发者底层框架使用的是springdoc-openapi
框架,则需要使用Knife4j
提供的对应版本,需要注意的是该版本没有Knife4j
提供的增强功能,是一个纯Ui。
com.github.xiaoymin
knife4j-springdoc-ui
3.0.2
自2.0.8
版本开始,Knife4j提供了轻量级的聚合微服务OpenAPI文档的中间件,可以在任意Spring Boot服务中聚合文档,最简单、最轻量级、最方便的聚合组件
com.github.xiaoymin
knife4j-aggregation-spring-boot-starter
2.0.8
该组件提供了4种不同的模式以满足不同语言、不同模式的方式进行OpenAPI文档的聚合
四种不同的方式:
更详细的介绍以及实战使用方法请参考文档
接口文档显示界面如下:
接口调试界面如下:
Swagger Models功能
支持导出离线Markdown、Html功能,markdown的表格较原先版本通过缩减显示为树形结构,点击预览导出离线Html效果 (opens new window),效果图如下:
通过第三方Markdown软件导出的PDF效果如下图:
同时提供了导出离线Html功能,Html功能界面风格和在线几乎没有区别,美观、大方、简洁,点击在线预览效果 (opens new window),
界面效果如下图:
感谢各位朋友的支持,前往https://gitee.com/xiaoym/knife4j (opens new window)点个Star吧~~ :)