跳到主要内容

[v2.0.3-2020/05/24 Knife4j 2.0.3发布,支持springdoc和i18n]

Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能的工具

文档https://doc.xiaominfo.com

效果(旧版)http://swagger-bootstrap-ui.xiaominfo.com/doc.html

效果(2.X版)http://knife4j.xiaominfo.com/doc.html

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://github.com/xiaoymin/swagger-bootstrap-ui

示例https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

特性 & 优化

knife4j

1、读取Markdown文件时,当文件不存在时日志错误信息简化打印,开发者可以忽略该错误gitee #I1E1S1

knife4j-spring-ui

1、移除Vue中的pwa机制,解决service-work.js引起的各种问题github #206

2、支持UiConfiguration中方法调试的配置,如并未配置任何支持的方法,在ui界面中不会出现调试栏Tab,代码如下:

@Bean
public UiConfiguration uiConfiguration(){
return UiConfigurationBuilder.builder()
.supportedSubmitMethods(new String[]{})
.build();
}

界面中的显示效果如下(仅显示文档):

3、GET请求出现参数未填的情况下发送Null的buggitee #I1BG4Ogithub #213

4、针对开发者在调试时更改接口地址,在接口地址中添加参数的情况,出现发送请求失败的buggitee #I1C5OQ

5、解决集成文档时各种basePath问题导致Ui的logo不显示的问题,通过Base64将logo图片转换处理,img标签直接显示base64字符串gitee #1CQ1F

6、左侧菜单栏在收缩状态下显示版本控制的标识导致菜单异常的问题,在收缩状态下禁用该项gitee #I1CCXTgitee #I1DBDF

7、增强功能忽略参数不完全的问题gitee PR#18

8、服务端在没有Write任何数据的情况下,针对非200状态码不显示状态的异常问题gitee #I1BKRH

9、针对raw类型的请求接口类型,全局参数中只能是header参数的问题,支持query类型的全局参数gitee #I1C86F

10、增加对Xml请求的适配支持,服务端consumes属性设为application/xml接口gitee #I1BCKB

11、增加@ApiSupport注解,分组Controller下可以设置全局author属性,或者order排序属性

12、剔除webjar文件中的favicon.ico文件,以避免和主项目产生冲突gitee #I1ELHNgithub #215

13、新增includeParameters属性,开发者可以在文档的参数中新增一种选择,该特性是和ignoreParameters对立,具体可以参考文档

14、优化在editor编辑器中的属性字段显示效果gitee #I1G3G9

15、导出的Html、Markdown离线文件添加作者属性gitee #I1EXXO

16、在Ui的全局参数配置中添加Header类型的请求参数后,非空情况下会自动合并每个接口的Header请求参数,接口中的Header如果和全局参数配置中的Header同名但是为空的情况下,Ui会使用全局参数配置中的Header参数gitee #I1GD87

17、优化请求数据类型的显示问题,Ui自动根据参数的类型识别出当前接口的请求类型并进行展示,解决springfox等框架始终解析为json请求的buggitee #I1EMJ9gitee #I1903T

18、修复请求头Content-Type在调试时被忽略的问题,该问题具体参考gitee #I18HGS,knife4j在2.x版本使用的是axios组件,axios针对发送的请求头data属性如果没有传递的情况下会忽略Content-Type请求头,具体可参考https://github.com/axios/axios/issues/86

19、添加I18n的支持,目前支持的语言:中文、English

20、请求头携带Cookie的情况,如果要使用Cookie,请求头的名称请确保为Cookie,不能有小写或其他.

21、添加对springdoc框架的集成支持,非常感谢teddygong提交的PR

如果你后端是Java+Spring的技术栈,在使用springfox的同时,想换一个Swagger的Ui皮肤,通过在pom.xml中直接引入即可,如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>2.0.3</version>
</dependency>

后端渲染OpenAPI的解析框架是springdoc,则添加如下依赖引用:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-springdoc-ui</artifactId>
<version>2.0.3</version>
</dependency>

Knife4j-Spring

使用Spring Boot的技术栈可以通过引用starter的方式快速引入使用,注意该starter组件是包含Ui的,如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.3</version>
</dependency>

如果是微服务的情况下,微服务其实不需要引用Ui的jar包,只需要在网关引用Ui的jar包依赖,所以在微服务情况下,使用增强属性只需要引用微服务版本的starter依赖,如下:

<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
<version>2.0.3</version>
</dependency>

Knife4j-Admin

knife4j-admin是一个基于Spring Cloud Gateway网关,通过网关的特性,结合knife4j对Swagger的文档进行动态聚合的管理平台

平台特点:

  • 跨语言、跨平台
  • 任意聚合Swagger文档,动态发布,调试
  • 文档个性化配置、权限等
  • 彻底告别聚合网关文档等由于软件版本等造成的技术集成问题
  • 独立部署

如果你有以上的需求的话,可以考虑使用一下knife4j-admin这个产品,产品文档点这里

特点

  • 基于Vue+Ant Design构建的文档,更强大、清晰的接口文档说明能力以及接口调试能力
  • 左右布局,基于Tabs组件的多文档查阅风格
  • 支持在线导出Html、Markdown、Word、PDF等多种格式的离线文档
  • 接口排序,支持分组及接口的排序功能
  • 支持接口全局在线搜索功能
  • 提供Swagger资源保护策略,保护文档安全
  • 接口调试支持无限参数,开发者调试非常灵活,动态增加、删除参数
  • 全局缓存调试信息,页面刷新后依然存在,方便开发者调试
  • 以更人性化的table树组件展示Swagger Models功能
  • 文档以多tab方式可显示多个接口文档
  • 请求参数栏请求类型、是否必填着颜色区分
  • 主页中粗略统计接口不同类型数量
  • 支持自定义全局参数功能,主页包括header及query两种类型
  • JSR-303 annotations 注解的支持
  • 更多个性化设置功能

界面

接口文档显示界面如下:

接口调试界面如下:

Swagger Models功能

支持导出离线Markdown、Html功能,markdown的表格较原先版本通过缩减显示为树形结构,点击预览导出离线Html效果,效果图如下:

通过第三方Markdown软件导出的PDF效果如下图:

同时提供了导出离线Html功能,Html功能界面风格和在线几乎没有区别,美观、大方、简洁,点击在线预览效果

界面效果如下图:

Star & Issue

感谢各位朋友的支持,前往https://gitee.com/xiaoym/knife4j点个Star吧~~ :)