# [v2.0.7-2020/11/02 Knife4j 2.0.7发布,细节处理]
# Knife4j 2.0.7发布,细节优化

`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

## 特性 & 优化

1、服务端创建Docket对象时配置`globalOperationParameters`参数时,header类型不选中或丢失的问题

2、如果服务端写会的json参数中包含base64的图片格式，在响应栏增加图片标签直接显示

![](/knife4j/images/blog/knife4j2.0.7/base1.png)

![](/knife4j/images/blog/knife4j2.0.7/base2.png)

3、springfox升级到2.10.5版本后，针对basePath会在解析时自动追加到path节点，因为以前的版本没有追加,所以会导致重复添加basePath的问题。[Gitee #I230K8](https://gitee.com/xiaoym/knife4j/issues/I230K8)、[Gitee #I23G5V](https://gitee.com/xiaoym/knife4j/issues/I23G5V)

4、导出出md离线文档请求参数部分字段的设置和文档中同步[Gitee #I22UFA](https://gitee.com/xiaoym/knife4j/issues/I22UFA)

5、字段参数说明支持`html`标签样式。[Gitee #I22RZ2](https://gitee.com/xiaoym/knife4j/issues/I22RZ2)

示例代码：

```java
@ApiModelProperty(value = "奖金名称,记住:<br /><span style=\"color:red\">我很重要</span>",example = "MVP奖杯")
private String name;
```

效果图：

![](/knife4j/images/blog/knife4j2.0.7/supporthtml.png)

6、默认去除小蓝点的版本控制，开发者可以通过在服务端通过配置进行开启,详情请参考[增强文档](https://doc.xiaominfo.com/knife4j/enhance.html)。

```yml
knife4j:
  enable: true
  setting:
	#是否开启界面中对某接口的版本控制,如果开启，后端接口变化后Ui界面会存在小蓝点
    enableVersion: true 
```

7、可以通过配置重命名界面Swagger Models的命名,详情请参考[增强文档](https://doc.xiaominfo.com/knife4j/enhance.html)，例如：

```yml
knife4j:
  enable: true
  setting:
    enableSwaggerModels: true
    swaggerModelName: 实体类列表
```

![](/knife4j/images/blog/knife4j2.0.7/swaggerModelName.png)

8、可以通过配置是否显示调试栏中的`AfterScript`功能，该属性默认为`true`,详情请参考[增强文档](https://doc.xiaominfo.com/knife4j/enhance.html)，例如：

```yml
knife4j:
  enable: true
  setting:
    enableAfterScript: false
```

![](/knife4j/images/blog/knife4j2.0.7/afterScript.png)

9、支持`@RequestMapping`注解中的`params`参数[Gitee #I22J5Q](https://gitee.com/xiaoym/knife4j/issues/I22J5Q)

10、`3.0`版本不支持`Authorize`的问题[Gitee #I22WVM](https://gitee.com/xiaoym/knife4j/issues/I22WVM)

11、增加局部刷新变量的按钮功能，可以通过服务端配置开启[Gitee #I22XXI](https://gitee.com/xiaoym/knife4j/issues/I22XXI)，该属性默认为`false`,详情请参考[增强文档](https://doc.xiaominfo.com/knife4j/enhance.html)，例如：

```yml
knife4j:
  enable: true
  setting:
    enableReloadCacheParameter: true
```

![](/knife4j/images/blog/knife4j2.0.7/reloadparameter.png)

12、修复兼容性bug，当升级后，默认`Swagger Models`以及`文档管理`功能丢失的问题

## 使用方法

Java开发使用`Knife4j`目前有一些不同的版本变化，主要如下：

1、如果开发者继续使用OpenAPI2的规范结构，底层框架依赖springfox2.10.5版本，那么可以考虑`Knife4j`的2.x版本

```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索2.X最新版本号-->
    <version>2.0.7</version>
</dependency>
```

2、如果开发者使用OpenAPI3的结构，底层框架依赖springfox3.0.0,可以考虑`Knife4j`的3.x版本

```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.1</version>
</dependency>
```

3、如果开发者底层框架使用的是`springdoc-openapi`框架,则需要使用`Knife4j`提供的对应版本,需要注意的是该版本没有`Knife4j`提供的增强功能，是一个纯Ui。

```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-springdoc-ui</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.1</version>
</dependency>
```

## 特点

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

## 界面

接口文档显示界面如下：

![](https://oscimg.oschina.net/oscnet/up-5b76509501c86174096f8b795d2aba8455b.png)

接口调试界面如下：

![](https://oscimg.oschina.net/oscnet/up-995a784219ea035cacd428d15d04e9cbcb3.png)

Swagger Models功能

![](https://oscimg.oschina.net/oscnet/up-98e1dbdf35ab957f5c05df126f9bae44ffd.png)

![](https://oscimg.oschina.net/oscnet/up-d9a030b06b76f9a4935205df453af149788.png)

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

![](https://oscimg.oschina.net/oscnet/up-cfb2256485835e29a39f96eaaa60251e08c.png)

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

![](https://oscimg.oschina.net/oscnet/up-44bb80532b9767a33650e178809f612c3e7.png)

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

界面效果如下图：

![](https://oscimg.oschina.net/oscnet/up-4deb56c65774b4dc2ad54f5278f31e89a5d.png)

## Star & Issue

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

 
 
 