# [v2.0.3-2020/05/24 Knife4j 2.0.3发布,支持springdoc和i18n]
`Knife4j`前身是`swagger-bootstrap-ui`,是一个为Swagger接口文档赋能的工具

**文档**：[https://doc.xiaominfo.com](https://doc.xiaominfo.com/)

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

**效果(2.X版)**：[http://knife4j.xiaominfo.com/doc.html](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

## 特性 & 优化

### knife4j

1、读取Markdown文件时,当文件不存在时日志错误信息简化打印,开发者可以忽略该错误[gitee #I1E1S1](https://gitee.com/xiaoym/knife4j/issues/I1E1S1)

### knife4j-spring-ui

1、移除Vue中的pwa机制,解决service-work.js引起的各种问题[github #206](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/206)

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

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

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

![](/knife4j/debug-1.png)

3、GET请求出现参数未填的情况下发送Null的bug[gitee #I1BG4O](https://gitee.com/xiaoym/knife4j/issues/I1BG4O)、[github #213](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/213)

4、针对开发者在调试时更改接口地址,在接口地址中添加参数的情况,出现发送请求失败的bug[gitee #I1C5OQ](https://gitee.com/xiaoym/knife4j/issues/I1C5OQ)

5、解决集成文档时各种basePath问题导致Ui的logo不显示的问题,通过Base64将logo图片转换处理,`img`标签直接显示base64字符串[gitee #1CQ1F ](https://gitee.com/xiaoym/knife4j/issues/I1CQ1F)

6、左侧菜单栏在收缩状态下显示版本控制的标识导致菜单异常的问题,在收缩状态下禁用该项[gitee #I1CCXT](https://gitee.com/xiaoym/knife4j/issues/I1CCXT)、[gitee #I1DBDF](https://gitee.com/xiaoym/knife4j/issues/I1DBDF)

7、增强功能忽略参数不完全的问题[gitee PR#18](https://gitee.com/xiaoym/knife4j/pulls/18)

8、服务端在没有Write任何数据的情况下,针对非200状态码不显示状态的异常问题[gitee #I1BKRH](https://gitee.com/xiaoym/knife4j/issues/I1BKRH)

9、针对raw类型的请求接口类型,全局参数中只能是header参数的问题,支持query类型的全局参数[gitee #I1C86F](https://gitee.com/xiaoym/knife4j/issues/I1C86F)

10、增加对Xml请求的适配支持,服务端`consumes`属性设为`application/xml`接口[gitee #I1BCKB](https://gitee.com/xiaoym/knife4j/issues/I1BCKB)

![](/knife4j/xml.png)

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

12、剔除webjar文件中的`favicon.ico`文件,以避免和主项目产生冲突[gitee #I1ELHN](https://gitee.com/xiaoym/knife4j/issues/I1ELHN)、[github #215](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/215)

13、新增`includeParameters`属性,开发者可以在文档的参数中新增一种选择,该特性是和`ignoreParameters`对立,具体可以参考[文档](https://doc.xiaominfo.com/knife4j/includeParameter.html)

14、优化在editor编辑器中的属性字段显示效果[gitee #I1G3G9](https://gitee.com/xiaoym/knife4j/issues/I1G3G9)

15、导出的Html、Markdown离线文件添加作者属性[gitee #I1EXXO](https://gitee.com/xiaoym/knife4j/issues/I1EXXO)

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

17、优化请求数据类型的显示问题,Ui自动根据参数的类型识别出当前接口的请求类型并进行展示,解决springfox等框架始终解析为json请求的bug[gitee #I1EMJ9](https://gitee.com/xiaoym/knife4j/issues/I1EMJ9)、[gitee #I1903T](https://gitee.com/xiaoym/knife4j/issues/I1903T)

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

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

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

21、添加对springdoc框架的集成支持，非常感谢[teddygong](https://gitee.com/teddygong)提交的PR

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

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

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

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

### Knife4j-Spring

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

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

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

```xml
<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这个产品，产品文档点[这里](https://doc.xiaominfo.com/solution/admin.html)

## 特点

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

## 界面

接口文档显示界面如下：

![](/knife4j/images/blog/knife4j2.0.2/1.png)

接口调试界面如下：

![](/knife4j/images/blog/knife4j2.0.2/8.png)

Swagger Models功能

![](/knife4j/images/blog/knife4j2.0.2/6.png)

![](/knife4j/images/blog/knife4j2.0.2/7.png)

支持导出离线Markdown、Html功能，markdown的表格较原先版本通过缩减显示为树形结构,[点击预览导出离线Html效果](https://doc.xiaominfo.com/html/knife4j-export-html.html)，效果图如下：

![](/knife4j/images/blog/knife4j2.0.2/3.png)

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

![](/knife4j/images/blog/knife4j2.0.2/4.png)

同时提供了导出离线Html功能,Html功能界面风格和在线几乎没有区别,美观、大方、简洁,[点击在线预览效果](https://doc.xiaominfo.com/Knife4j-Offline-Html.html)，

界面效果如下图：

![](/knife4j/images/blog/knife4j2.0.2/5.png)

## Star & Issue

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

 
 
 