02 Knife4j 2.0.7发布,细节处理]

# Knife4j 2.0.7发布,细节优化

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

文档：https://doc.xiaominfo.com (opens new window)

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

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

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的图片格式，在响应栏增加图片标签直接显示

3、springfox升级到2.10.5版本后，针对basePath会在解析时自动追加到path节点，因为以前的版本没有追加,所以会导致重复添加basePath的问题。Gitee #I230K8 (opens new window)、Gitee #I23G5V (opens new window)

4、导出出md离线文档请求参数部分字段的设置和文档中同步Gitee #I22UFA (opens new window)

5、字段参数说明支持html标签样式。Gitee #I22RZ2 (opens new window)

示例代码：

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

效果图：

6、默认去除小蓝点的版本控制，开发者可以通过在服务端通过配置进行开启,详情请参考增强文档 (opens new window)。

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

7、可以通过配置重命名界面Swagger Models的命名,详情请参考增强文档 (opens new window)，例如：

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

8、可以通过配置是否显示调试栏中的AfterScript功能，该属性默认为true,详情请参考增强文档 (opens new window)，例如：

knife4j:
  enable: true
  setting:
    enableAfterScript: false

9、支持@RequestMapping注解中的params参数Gitee #I22J5Q (opens new window)

10、3.0版本不支持Authorize的问题Gitee #I22WVM (opens new window)

11、增加局部刷新变量的按钮功能，可以通过服务端配置开启Gitee #I22XXI (opens new window)，该属性默认为false,详情请参考增强文档 (opens new window)，例如：

knife4j:
  enable: true
  setting:
    enableReloadCacheParameter: true

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

# 使用方法

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

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

<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版本

<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。

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