knife4j 发行版 - Gitee.com

最新版

v4.5.0

030ad00

2024-01-08 10:46

Knife4j 4.5.0版本发布，助力橙单低代码平台OpenAPI3.0规范顺利落地

**完整的更新日志**: https://gitee.com/xiaoym/knife4j/commits/v4.5.0

## 本次迭代

4.5.0版本主要更新如下：

1、前端i18n增加对日语的支持，感谢[一堃通行](https://gitee.com/mao-junkun) ,[Gitee#PR98](https://gitee.com/xiaoym/knife4j/pulls/98)

2、修复EnvironmentPostProcessor中存在defaultProperties与业务冲突的问题，感谢leilei，[Gitee#PR100](https://gitee.com/xiaoym/knife4j/pulls/100)

3、修复addOrderExtension方法报错空指针问题，感谢doublek24[Gitee#PR99](https://gitee.com/xiaoym/knife4j/pulls/99)

4、Spring Boot3 中排序order不生效的问题

5、OpenAPI3规范中未配置`springdoc.group-configs.packages-to-scan`属性导致的空指针异常[Gitee#I8O7E8](https://gitee.com/xiaoym/knife4j/issues/I8O7E8)

6、实体参数，`@Schema`的description属性显示的异常问题[Gitee#I8EVO3](https://gitee.com/xiaoym/knife4j/issues/I8EVO3)、[Github#690](https://github.com/xiaoymin/knife4j/issues/690)

7、OpenAPI3规范请求类型针对`format`属性的展示问题[Gitee#I8KRWV](https://gitee.com/xiaoym/knife4j/issues/I8KRWV)

8、自定义文档】多服务聚合后如果服务名包含"-"会导致自定义文档页刷新报错[Gitee#I8EKAQ](https://gitee.com/xiaoym/knife4j/issues/I8EKAQ)

9、移除文档`favicon.ico`的引用[Github#716](https://github.com/xiaoymin/knife4j/issues/716)

最后提交信息为： docs:更新日志

v4.4.0

f87ff50

2023-12-10 18:45

Knife4j v4.4.0 发布，OpenAPI自动注册功能实现

1、针对eureka注册中心将服务名称转大写的情况，knife4j-gateway聚合失败的处理，感谢[DongLiusuo](https://gitee.com/dongliusuo)PR贡献[Gitee#93](https://gitee.com/xiaoym/knife4j/pulls/93)

2、debug发送body请求下载的情况下返回文件乱码

3、网关聚合场景下，springdoc子服务默认default地址404的问题优化[Gitee#I7RAP7](https://gitee.com/xiaoym/knife4j/issues/I7RAP7)

4、knife4j-gateway组件在boot3中basic密码不兼容的情况[#pr652](https://github.com/xiaoymin/knife4j/pull/652)

5、SpringBoot3环境下的javax.filter的兼容性问题修复[Github#667](https://github.com/xiaoymin/knife4j/issues/667)

6、OpenAPI3规范下默认无分组情况下显示分组名称的优化

7、修复**SecurityDocketUtils对SecurityContext的Reference绑定错误的问题[Gitee#I88IYH](https://gitee.com/xiaoym/knife4j/issues/I88IYH)**

8、导出的离线Html文档引用CDN源替换为国内的源[Gitee#I8C85P](https://gitee.com/xiaoym/knife4j/issues/I8C85P)

9、springdoc-openapi版本升级到2.3.0版本

10、spring-EnvironmentPostProcessor中存在defaultProperties与业务冲突的问题，主要是springfox兼容高版本boot的问题修复[Github#686](https://github.com/xiaoymin/knife4j/issues/686)

11、针对Authorization不生效的问题请参考博客:[OpenAPI3规范中添加Authorization鉴权请求Header不生效？](/docs/blog/add-authorization-header)

最后提交信息为： docs:文档更新

v4.3.0

d0169ad

2023-08-07 08:54

Knife4j v4.3.0 发布，深挖Gateway网关聚合场景,解决各种疑难杂症

大家好，Knife4j v4.3.0版本发版，本次版本发版主要解决问题：

4.3.0版本主要解决在Spring Cloud Gateway网关组件下聚合Swagger2或者OpenAPI3提供最简单的配置，简化开发者工作。

最简单的配置如下(4个配置属性完成所有子服务的网关聚合)：

```yaml
knife4j:
  gateway:
    enabled: true
    strategy: discover
    discover:
      # 聚合所有子服务(swagger2规范)，子服务是3规范则替换为openapi3
      version: swagger2
      enabled: true
```

Maven坐标
```xml
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

```

## 更新日志

### 优化`knife4j-gateway`组件

1、在gateway网关聚合服务中，排除其他服务支持**正则表达式**
```yaml
knife4j:
  gateway:
    enabled: true
    strategy: discover
    discover:
      version: swagger2
      enabled: true
      excluded-services:
        # 排除order开头的配置
        - order.*
```

2、聚合子服务时，两个子服务是根路由转发时只聚合单个服务的bug(主要是`order`排序属性导致)

3、启用`DisocverClient`作为网关默认转发路由场景下聚合失败的问题

4、针对Swagger2规范聚合失败的问题

5、在手动聚合模式(manual)下同时支持`swagger2`和`openapi3`规范的聚合
```yaml
knife4j:
  gateway:
    enabled: true
    strategy: manual
    routes:
      # swagger2
      - name: 订单openapi2
        service-name: user-service
        url: /order-service-openapi2/v2/api-docs?group=default
        context-path: /
      # openapi3
      - name: 订单openapi3
        service-name: order-service
        url: /order/v3/api-docs/default
        context-path: /order
```

6、在子服务全部是swagger2规范情况下contextPath路径错误的问题

7、**优化`knife4j-gateway`的部分代码结构及聚合场景**，目前聚合子服务路由在服务发现(`discover`)模式下主要4种模式，主要包括：

- 基于Spring Cloud Gateway配置的routes规则解析子服务路由，数据来源：`spring.cloud.gateway.routes`
- 在discover服务发现场景下，针对自定义添加的routes，默认再次追加，数据来源：`knife4j.gateway.routes`
- 服务发现discover模式下，开发者在网关成的路由转发模式默认通过`DiscoveryClient`的默认方式转发路由，规则是`pattern:/service-id/** `
- 接收编码方式动态注入Spring Cloud Gateway网关的路由，进行聚合转发

### 其他部分

1、修复`@ApiSupport`注解不生效的问题[Gitee#PR89](https://gitee.com/xiaoym/knife4j/pulls/89)

2、数据存在枚举值时，SwaggerModel无法正常展开[Gitee#PR90](https://gitee.com/xiaoym/knife4j/pulls/90)

3、解决组件冲突的问题[GitHub#630](https://github.com/xiaoymin/knife4j/issues/620)

4、增加title属性的支持[Gitee#I7KUYP](https://gitee.com/xiaoym/knife4j/issues/I7KUYP)

## 感谢

非常感谢以下开发者的PR贡献(排名不分先后)：

- [lhzsdnu](https://gitee.com/lhzsdnu)
- [igeekfan](https://gitee.com/igeekfan)

## 最后

感兴趣的朋友可以加群参与讨论贡献

关注公众号 "Knife4j"，点击菜单获取加群二维码

![](https://foruda.gitee.com/images/1661053867569480310/%E6%89%AB%E7%A0%81_%E6%90%9C%E7%B4%A2%E8%81%94%E5%90%88%E4%BC%A0%E6%92%AD%E6%A0%B7%E5%BC%8F-%E6%A0%87%E5%87%86%E8%89%B2%E7%89%88.png)

最后提交信息为： docs:更新文档

v4.2.0

cf51c25

2023-08-01 08:53

Knife4j v4.2.0 发布，Gateway网关聚合组件优化

大家好，Knife4j v4.2.0版本发版，本次版本发版主要解决问题：

## 更新日志

### ⛰️ 依赖升级

1、升级boot3版本为3.0.7、springdoc版本‣

2、springdoc版本升级，主要包括：

- 针对Spring Boot2版本的，升级springdoc版本到1.7.0
- 针对Spring Boot3版本的，升级springdoc版本到2.1.0

### 🏕️ 优化`knife4j-gateway`组件

1、针对服务发现模式(`discover`)，可以动态读取服务转发路由配置前缀prefix，开发者可不用在独立配置，感谢[当幸福碰错了头](https://gitee.com/chenshifeng001)PR

2、支持除`default`默认分组外的多分组类型，感谢[谢进伟](https://gitee.com/xiejinwei)PR

3、针对在Dubbo场景下会出现聚合各个Service的场景，该版本提供自动排除服务的扩展SPI接口，开发者可集成自动扩展实现规则进行聚合服务的排除，参考[Gitee#I6YLMB](https://gitee.com/xiaoym/knife4j/issues/I6YLMB)

```javascript
@Slf4j
@Component
public class MyExcludeService implements GatewayServiceExcludeService {
    @Override
    public Set<String> exclude(Environment environment, Knife4jGatewayProperties properties, List<String> services) {
        log.info("自定义过滤器.");
        if (!CollectionUtils.isEmpty(services)){
						// 排除注册中心包含order字眼的服务
            return services.stream().filter(s -> s.contains("order")).collect(Collectors.toSet());
        }
        return new TreeSet<>();
    }
}
```

4、解决在Nginx等二级代理转发情况下的路径错误问题[Gitee#gitee](https://gitee.com/xiaoym/knife4j/issues/I73AOG)、[GitHub#609](https://github.com/xiaoymin/knife4j/issues/609)、[Gitee#I6KYUJ][https://gitee.com/xiaoym/knife4j/issues/I6KYUJ]、[GitHub#603](https://github.com/xiaoymin/knife4j/issues/603)、[GitHub#586](https://github.com/xiaoymin/knife4j/issues/586)

5、增加对子服务的排序规则设置，配置如下：

```yaml
knife4j:
	gateway:
		tags-sorter: alpha # 接口排序规则
        operations-sorter: alpha
```

不管是tag还是operation，排序规则主要提供两种实现方式：

- alpha：官方swagger-ui的默认排序规则实现。
- order：*nife4j提供的增强排序规则，开发者可在子服务中扩展x-order，根据数值来自定义排序*

6、knife4j-gateway组件增加basic验证GitHub#555

### 🏝️ Ui更新

1、Script脚本生成的TypeScript代码增加注释[Gitee#I6T78E](https://gitee.com/xiaoym/knife4j/issues/I6T78E)、[GitHub#568](https://github.com/xiaoymin/knife4j/issues/568)

2、OAS2新增allof特性的支持[Github#PR589](https://github.com/xiaoymin/knife4j/pull/589)

3、针对`jakarta`环境中Basic的属性提示已经match优化[GitHub#578](https://github.com/xiaoymin/knife4j/issues/578)

### ⛺ 增强部分

1、openapi3规范中增加对`@ApiSupport`增强注解的支持[Gitee#I79WIJ](https://gitee.com/xiaoym/knife4j/issues/I79WIJ)

2、Post发送请求query的方式修改[Gitee#I7DNRP](https://gitee.com/xiaoym/knife4j/issues/I7DNRP)

3、优化基础jar包的引用关系，lombok、slf4j等jar包级别改为`provided`[GitHub#591](https://github.com/xiaoymin/knife4j/issues/591)

## 🤝 感谢

非常感谢以下开发者的PR贡献(排名不分先后)：

- [当幸福碰错了头](https://gitee.com/chenshifeng001)
- [谢进伟](https://gitee.com/xiejinwei)
- [最怕的、其实是孤单。。。](https://gitee.com/sky-0914)
- [fengshi20102010](https://gitee.com/fengshi20102010)
- [zskzskabcd](https://github.com/zskzskabcd)
- [小魏,小魏,我们要去哪里呀](https://github.com/galaxy-sea)
- [Pastors](https://github.com/Pastor0370)
- [King-Run](https://github.com/King-Run)
- [liuyd-cc](https://github.com/liuyd-cc)

最后提交信息为： docs:更新文档

v4.1.0

9fc3351

2023-03-24 08:43

Knife4j v4.1.0 发布，Gateway网关聚合更上一层楼

大家好，Knife4j v4.1.0版本发版，本次版本发版主要解决两个问题：

- **🐛常规Bug修复**：主要针对v4.0版本的异常bug、ui兼容性问题修复
- **🎄Spring Cloud Gateway网关聚合组件升级**：提供手动、服务发现两种模式，轻松聚合OpenAPI文档

## 主要更新

### 🐛常规bug修复

1、网关聚合组件knife4j-gateway-spring-boot-starter针对OpenAPI3规范聚合时丢失context-path的支持，在ui层面做兼容

2、springdoc-openapi版本升级到最新版本1.6.15、2.0.4 [Gitee#I6OIB1](https://gitee.com/xiaoym/knife4j/issues/I6OIB1)

3、`knife4j-openapi3-jakarta-spring-boot-starter`模块属性配置在idea不提示的异常情况处理

4、增强属性自定义文档加载分组的bug处理[GitHub#PR525](https://github.com/xiaoymin/swagger-bootstrap-ui/pull/525)

5、`knife4j-dependencies`模块漏掉部分依赖模块版本定义的情况

6、解决不添加 springdoc-openapi-ui 依赖异常的问题[Gitee#I66YJA](https://gitee.com/xiaoym/knife4j/issues/I66YJA)**

7、针对OAS3规范中Parameter属性缺失字段说明的异常情况修复

8、针对OAS3规范中扩展属性包括排序、作者等不生效的问题[Gitee#I6FB9I](https://gitee.com/xiaoym/knife4j/issues/I6FB9I)

9、部分字段翻译问题[GitHub#540](https://github.com/xiaoymin/knife4j/issues/540)

10、使用增强属性开启`production`时出现的NPE异常[GitHub#527](https://github.com/xiaoymin/knife4j/issues/527)

11、针对OpenAPI3规范的tag名称兼容性问题[Gitee#I6JATP](https://gitee.com/xiaoym/knife4j/issues/I6JATP)

12、实体类接收url参数时文档不显示参数说明的问题[Gitee#I6H8CD](https://gitee.com/xiaoym/knife4j/issues/I6H8CD)

13、修复OAS3规范上传组件的识别问题[Gitee#I6HAW0](https://gitee.com/xiaoym/knife4j/issues/I6HAW0)、[GitHub#538](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/538)

14、SpringWebflux框架的集成组件starter封装[GitHub#521](https://github.com/xiaoymin/knife4j/issues/521)

15、针对Basic验证的特性增加include属性，允许开发者自定义配置[GitHub#530](https://github.com/xiaoymin/knife4j/issues/530)

16、全局搜索框支持tag名称的模糊搜索[Gitee#I6NWV6](https://gitee.com/xiaoym/knife4j/issues/I6NWV6)

### 🎄Spring Cloud Gateway网关聚合组件升级

在v4.1.0版本中，继续升级Spring Cloud Gateway网关聚合组件，提供`discover`服务发现的模式，自动聚合OpenAPI文档。使用方式更加简单，一个Starter组件+yml配置，即可完成网关层的聚合。

1、引入starter依赖，maven坐标如下：

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

2、基于`discover`模式自动聚合注册中心的文档，则最简洁的配置如下：

> 更多场景case的使用，可以参考[knife4j-gateway-discussions](https://github.com/xiaoymin/knife4j/discussions/547)

```yml
knife4j:
    enable: true
    # 指定服务发现的模式聚合微服务文档，并且是默认`default`分组
    strategy: discover
    discover：
        enable: true
        # 指定版本号(Swagger2|OpenAPI3)
        version : openapi3

```

如此，我们的聚合工作就完成了。

在浏览器访问Knife4j提供的文档地址：`http://ip:网关端口/doc.html`

# 示例程序

正是由于 4.0 的文档还在输出中，因此 Knife4j 在 4.0 新版本中也提供了不同版本的示例程序

示例如下：

- Spring Boot 2.x + OpenAPI2 规范：[knife4j-spring-boot27-demo](https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-spring-boot27-demo)
- Spring Boot 2.x +OpenAPI3 规范：[knife4j-springdoc-openapi-demo](https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-springdoc-openapi-demo)
- Spring Boot 3+ OpenAPI3 规范：[knife4j-spring-boot3-demo](https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-spring-boot3-demo)
- Spring Cloud Gateway网关聚合：[knife4j-openapi3-gateway](https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-openapi3-gateway)

# 社区

**感兴趣的朋友可以加群参与讨论贡献**

关注公众号 "Knife4j"，点击菜单获取加群二维码

![输入图片说明](https://foruda.gitee.com/images/1661053867569480310/%E6%89%AB%E7%A0%81_%E6%90%9C%E7%B4%A2%E8%81%94%E5%90%88%E4%BC%A0%E6%92%AD%E6%A0%B7%E5%BC%8F-%E6%A0%87%E5%87%86%E8%89%B2%E7%89%88.png)

仓库坐标

- Gitee：[https://gitee.com/xiaoym/knife4j](https://gitee.com/xiaoym/knife4j)
- GitHub:[https://github.com/xiaoymin/knife4j](

最后提交信息为： perf:Knife4jInsight版本升级

v4.0.0

c651dc8

2022-12-20 16:19

Knife4j 4.0正式发布,新征程！！！

Knife4j 4.0版本今天正式发布了！ 🎉🎉🎉

该版本处理了近12个月以来Gitee、GitHub两大平台积压的近300多个issue

同时也带来了一些新的特性。

**主要更新亮点：**

- 🆕统一各个组件版本号,使用Knife4j时开发者根据需要自行引用,**artifactId发生了变化**
- 💯**支持`Spring Boot 3`**
- 🌼兼容适配`springdoc-openapi`底层框架，全面迁移到`OpenAPI3`的规范支持
- 🌿针对OpenAPI2(Swagger)规范提供了优化，开发者基于Spring Boot2版本可以无缝衔接
- 💪Knife4j-Desktop组件架构升级重写，新架构支持不同需求的OpenAPI规范进行聚合
- 💪提供官方Docker镜像服务，基于Knife4j可方便在云服务上进行使用
- 💥官网文档更新重写

# 架构整理

为了以后Knife4j发展的可持续性，整个架构重新梳理，后续可以根据不同的需求，提供不同的服务
![输入图片说明](https://foruda.gitee.com/images/1671524372859872318/dd4d6bc8_118100.png "屏幕截图")

新的架构图，有的是规划(尚未实现)，有的已经实现，欢迎大佬一起贡献。

# 统一版本

在此次4.0版本中，统一各个版本，将OpenAPI2规范与OpenAPI3规范区分开，避免版本及规范混乱使用产生的误解，使用者可以更清晰

**需要注意，4.0版本`artifactId`发生了变化**

目前`knife4j`的项目结构：

| 模块名称                                     | 说明                                                         |
| -------------------------------------------- | ------------------------------------------------------------ |
| knife4j-aggregation-spring-boot-starter      | 基于 Servlet 体系下的聚合中间件                              |
| knife4j-core                                 | 核心类,包含一些工具包、增强注解等                            |
| knife4j-dependencies                         | Knife4j 提供的 dependencies 工程，引入该工程后，knife4j\springfox\swagger\springdoc-openapi 等版本号不用在独自声明 |
| knife4j-openapi2-ui                          | 增强 UI 文档,该包是一个 webjar,只包含前端代码，支持 OpenAPI2 |
| knife4j-openapi3-ui                          | 增强 UI 文档,该包是一个 webjar,只包含前端代码，支持 OpenAPI3 |
| knife4j-gateway-spring-boot-starter          | 基于Spring Cloud Gateway网关的项目可以引用该组件实现简单的文档聚合,参考https://gitee.com/xiaoym/knife4j/tree/dev/knife4j/knife4j-gateway-spring-boot-starter |
| knife4j-openapi2-spring-boot-starter         | 基于 OpenAPI2 规范，在 Spring Boot < 3.0.0-M1 的单体架构下可以直接引用此 starter,该模块包含了 Ui 部分，底层依赖 springfox-swagger 2.10.5 项目 |
| knife4j-openapi3-spring-boot-starter         | 基于 OpenAPI3 规范，在 Spring Boot < 3.0.0-M1 的单体架构下可以直接引用此 starter,该模块包含了 Ui 部分，底层基于 springdoc-openapi 项目 |
| knife4j-openapi3-jakarta-spring-boot-starter | 基于 OpenAPI3 规范，在 Spring Boot >= 3.0.0-M1 的单体架构下可以直接引用此 starter,该模块包含了 Ui 部分，底层基于 springdoc-openapi 项目 |

开发者继续使用Spring Boot 2以及OpenAPI2的规范

> 该starter底层依然依赖springfox项目，版本2.10.5

可以使用`knife4j-openapi2-spring-boot-starter`,maven坐标如下：

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

开发者使用Spring Boot 2以及OpenAPI3规范，那需要考虑在项目的注解上做迁移变更，并且knife4j 4.0版本针对3的规范底层迁移使用springdoc-openapi项目，放弃springfox3.0

可以使用`knife4j-openapi3-spring-boot-starter`,maven坐标如下：

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

# 支持Spring Boot 3

开发者使用Spring Boot 3以及使用OpenAPI3规范

可以使用`knife4j-openapi3-jakarta-spring-boot-starter`,maven坐标如下：

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

# Knife4j配置属性变化

此次Knife4j提供的Spring Boot Starter组件，增强配置属性通过`spring-boot-configuration-processor`工具自动生成`spring-configuration-metadata.json`描述性文件，因此，不同于之前的版本，配置属性会将之前的命名大写全部转为下划线

**Knife4j之前的增强配置属性(`老的`)：**

```yaml
knife4j:
  enable: true
# 以setting配置为例
  setting:
    language: zh-CN
    enableSwaggerModels: true
    enableDocumentManage: true
```

**Knife4j 4.0配置的增强属性(`新的`):**

```yaml
knife4j:
  enable: true
  setting:
    custom-code: 500
    enable-footer-custom: false
    footer-custom-content: 我是自定义的Footer
```

# springdoc-openapi项目增强适配

Knife4j之前的版本一直都是基于springfox项目提供了增强功能，此次4.0版本针对springdoc-openapi项目也提供了增强，Knife4j提供的增强功能可以无缝在OpenAPI3的规范中使用

# Knife4j独立服务工具架构升级

Knife4j在此次版本中针对聚合OpenAPI规范文档提供了独立的服务组件

整个架构重新设计，代码重写，并将该服务发布到Docker官方镜像仓库，支持不同配置中心中间件对接，数据+应用进行分离，OpenAPI的数据源可以轻松放到配置中心中，实现文档的聚合

架构图如下：
![输入图片说明](https://foruda.gitee.com/images/1671524360006376628/f165f256_118100.png "屏幕截图")

# 文档

Knife4j新版本文档采用新的模板，可以区分不同的版本，方便开发使用者PR贡献或者查看

![输入图片说明](https://foruda.gitee.com/images/1671524353878915201/57e56eca_118100.png "屏幕截图")

> ❗4.0版本的文档作者正在疯狂码字中…….敬请期待.

# 示例程序

正是由于4.0的文档还在输出中，因此Knife4j在4.0新版本中也提供了不同版本的示例程序

示例如下：

- Spring Boot 2.x + OpenAPI2规范：[knife4j-spring-boot27-demo](https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-spring-boot27-demo)
- Spring Boot 2.x +OpenAPI3规范：[knife4j-springdoc-openapi-demo](https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-springdoc-openapi-demo)
- Spring Boot 3+ OpenAPI3规范：[knife4j-spring-boot3-demo](https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-spring-boot3-demo)

# 社区

**感兴趣的朋友可以加群参与讨论贡献**

关注公众号"Knife4j"，点击菜单获取加群二维码
![输入图片说明](https://foruda.gitee.com/images/1671524329760963345/4e1568af_118100.png "屏幕截图")

整个4.0版本从确定开发方向以及迭代过程，感兴趣的朋友可以通过该issue了解：

https://gitee.com/xiaoym/knife4j/issues/I5LIQZ

最后提交信息为： build:v4.0.0 RELEASE

v2.0.9

be0819f

2021-06-28 19:15

Knife4j 2.0.9 发布，解决 issue 150+

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

**文档**：[https://xiaoym.gitee.io/knife4j/](https://xiaoym.gitee.io/knife4j/)

**效果(旧版)**：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

## 日志

### OpenAPI3

1、在OpenAPI3.0规范中针对下载请求对象显示错误的优化[Gitee#I374SP](https://gitee.com/xiaoym/knife4j/issues/I374SP)

2、针对OpenAPI3规范中对于`binary`类型的format属性，上传组件不显示的问题[Gitee#I34NOS](https://gitee.com/xiaoym/knife4j/issues/I34NOS)、[Gitee #I3BRWT](https://gitee.com/xiaoym/knife4j/issues/I3BRWT)

3、OpenAPI3.0规范中Swagger models 中的枚举显示[PR #43](https://gitee.com/xiaoym/knife4j/pulls/43)、[Gitee #I3DP8P](https://gitee.com/xiaoym/knife4j/issues/I3DP8P)

4、针对OpenAPI3.0规范权限拦截问题增加接口地址[Gitee #I2810R](https://gitee.com/xiaoym/knife4j/issues/I2810R)、[Gitee #I3HSK4](https://gitee.com/xiaoym/knife4j/issues/I3HSK4)

5、针对OpenAPI3规范支持请求参数中包含`$ref`的问题[Gitee #I2A89C](https://gitee.com/xiaoym/knife4j/issues/I2A89C)

6、针对OpenAPI3规范中图片预览的问题优化[Gitee #I3IUUQ](https://gitee.com/xiaoym/knife4j/issues/I3IUUQ)

### 聚合组件aggregation

1、聚合组件针对Cloud模式转发HTTP请求时，请求头重复导致转发失败的问题[Gitee #PR39](https://gitee.com/xiaoym/knife4j/pulls/39)

2、aggregation聚合组件增加order属性，方便开发者排序设置聚合OpenAPI文档的顺序[Gitee #I27ST2](https://gitee.com/xiaoym/knife4j/issues/I27ST2)

3、aggregation聚合组件Nacos聚合微服务文档支持Nacos用户名及密码访问OpenAPI接口[Gitee #I28IF9](https://gitee.com/xiaoym/knife4j/issues/I28IF9)

4、聚合组件日志打印信息优化，增加`isDebugEnabled`逻辑判断,日志级别全部由`info`改为`debug`级别[Gitee #I39QPL](https://gitee.com/xiaoym/knife4j/issues/I39QPL)

5、聚合组件响应Model不显示的问题[Gitee #I3EMZE](https://gitee.com/xiaoym/knife4j/issues/I3EMZE)

6、聚合组件没有正确响应接口的状态码信息[PR #44](https://gitee.com/xiaoym/knife4j/pulls/44)

7、基于`Eureka/Nacos`注册中心的聚合组件，增加心跳检测机制(`30s/per`)，自动剔除已经下线的服务,保证聚合文档的正常访问[Gitee #I2CKQT](https://gitee.com/xiaoym/knife4j/issues/I2CKQT)、[Gitee #I2CDCK](https://gitee.com/xiaoym/knife4j/issues/I2CDCK)、[Gitee #I2KUUY](https://gitee.com/xiaoym/knife4j/issues/I2KUUY)

8、`Cloud`模式增加心跳检测机制(`30s/per`)，自动剔除已经下线的服务,保证聚合文档的正常访问

8、聚合组件转发文件时参数丢失的问题[Gitee #I39OXE](https://gitee.com/xiaoym/knife4j/issues/I39OXE)

### 常规

1、OAuth2授权`Content-Type`的异常问题[Gitee#PR35](https://gitee.com/xiaoym/knife4j/pulls/35)、[Gitee#I2CKHA](https://gitee.com/xiaoym/knife4j/issues/I2CKHA)

2、OAuth2判断异常的问题[Gitee #PR37](https://gitee.com/xiaoym/knife4j/pulls/37)

3、修复离线导出Markdown文档自定义文档为`undefined`的问题[Gitee#I2EDI8](https://gitee.com/xiaoym/knife4j/issues/I2EDI8)、[Gitee #I2WCQG](https://gitee.com/xiaoym/knife4j/issues/I2WCQG)

4、日志的打印优化[Gitee #I39QPL](https://gitee.com/xiaoym/knife4j/issues/I39QPL)

5、微服务聚合时`basePath`不追加的问题[Gitee #I3B5BK](https://gitee.com/xiaoym/knife4j/issues/I3B5BK)、[Gitee #I3EEJ3](https://gitee.com/xiaoym/knife4j/issues/I3EEJ3)

6、针对List类型示例值多出换行符的问题[Gitee #I2D6D4](https://gitee.com/xiaoym/knife4j/issues/I2D6D4)

7、解决Form类型上传参数时传递`Null`的问题[Gitee #I3AHDQ](https://gitee.com/xiaoym/knife4j/issues/I3AHDQ)

8、针对个性化配置的保存问题修改逻辑，开发者通过界面保存个性化配置后丢失的问题[Gitee #I27CN8](https://gitee.com/xiaoym/knife4j/issues/I27CN8)、[Gitee #I2CBZQ](https://gitee.com/xiaoym/knife4j/issues/I2CBZQ)、[Gitee #I2978Y](https://gitee.com/xiaoym/knife4j/issues/I2978Y)、[Gitee #I3IEXT](https://gitee.com/xiaoym/knife4j/issues/I3IEXT)、[Gitee #I3Q0MO](https://gitee.com/xiaoym/knife4j/issues/I3Q0MO)、[Gitee #I3QSAN](https://gitee.com/xiaoym/knife4j/issues/I3QSAN)

9、针对接口分组中不存在API接口时出现链接点击空白的问题处理，如果分组下没有API接口,默认点击显示主页[Gitee #I2CVTF](https://gitee.com/xiaoym/knife4j/issues/I2CVTF)

10、OpenAPI规范中tags缺失时导致接口不显示的问题优化,增加`default`默认分组[Gitee #I27M98](https://gitee.com/xiaoym/knife4j/issues/I27M98)

11、针对服务端使用`@RequestMapping`注解通过`method`限定方法类型时，Ui增强功能过滤不生效的问题[Gitee #I28RJ5](https://gitee.com/xiaoym/knife4j/issues/I28RJ5)

12、文件上传类型接口请求数据显示类型错误的情况改进，根据参数设置接口请求数据类型为`multipart/form-data`[Gitee #I29KMH](https://gitee.com/xiaoym/knife4j/issues/I29KMH)

13、优化响应`html/xml/text`等内容时展现方式[Gitee #I2A0QA](https://gitee.com/xiaoym/knife4j/issues/I2A0QA)

14、分组下拉框搜索失效的问题[Gitee #I3BAOK](https://gitee.com/xiaoym/knife4j/issues/I3BAOK)

15、优化OpenAPI版本判断的逻辑,根据响应OpenAPI规范JSON再判断获取当前的规范版本，防止出现空异常或Model不显示等问题[Gitee #I37X0Q](https://gitee.com/xiaoym/knife4j/issues/I37X0Q)、[Gitee #I3EMZE](https://gitee.com/xiaoym/knife4j/issues/I3EMZE)

16、针对`JSON`请求格式的提交，增加`Beantify`按钮，可以对文本格式化美化的功能[Gitee #I39MUP](https://gitee.com/xiaoym/knife4j/issues/I39MUP)

17、调试发送时增强`loading`效果体验[Gitee #I3BG5V](https://gitee.com/xiaoym/knife4j/issues/I3BG5V)

18、SwaggerModels 内容太长不会自动换行的问题[Gitee #I3QC02](https://gitee.com/xiaoym/knife4j/issues/I3QC02)

19、针对Map属性的结构展示异常的问题[Gitee #I37WB7](https://gitee.com/xiaoym/knife4j/issues/I37WB7)

20、解决`afterScript`特性不能添加多个参数的问题[Gitee #I3OJUW](https://gitee.com/xiaoym/knife4j/issues/I3OJUW)

21、优化响应内容判断`base64`导致效率低下的问题[Gitee #I2VRD5](https://gitee.com/xiaoym/knife4j/issues/I2VRD5)。

22、针对增强注解`@ApiOperationSupport`提供的`ignoreParameters`属性提供正则模式的忽略策略支持[Gitee #I21ZKC](https://gitee.com/xiaoym/knife4j/issues/I21ZKC)

最后提交信息为： !47 Knife4j 2.0.9 发布，解决 issue 150+

v2.0.8

fd6f2d9

2020-11-23 09:49

Knife4j 2.0.8发布,轻量级微服务聚合文档中间件诞生

1、构建响应curl时，去除Knife4j自定义添加的部分Header头

2、增加自定义主页的增强配置，开发者可以提供一个Markdown文档，用来自定义Home主页显示的内容[Gitee #I24ZXI](https://gitee.com/xiaoym/knife4j/issues/I24ZXI)

```yml
knife4j:
	enable: true
	setting:
		# 是否自定义显示Home主页，默认为false
		enableHomeCustom: true
		# 自定义主页Home的markdown文档路径,只能设置1个，如果设置为目录，则默认取第一个
		homeCustomLocation: classpath:markdown/home.md
```

3、OpenAPI开放接口可以通过增强配置是否显示[Gitee #I25273](https://gitee.com/xiaoym/knife4j/issues/I25273)

```yml
knife4j:
	enable: true
	setting:
		# 是否显示文档中的Open标签栏，默认为true
		enableOpenApi: false
```

4、搜索框可以通过增强配置是否显示[Gitee #I24ZYY](https://gitee.com/xiaoym/knife4j/issues/I24ZYY)

```yml
knife4j:
	enable: true
	setting:
		# 是否显示文档中的搜索框，默认为true，即显示
		enableSearch: false
```

5、文档最下边的footerkey通过增强配置是否显示，并且可以自定义显示内容[Gitee #I24ZYD](https://gitee.com/xiaoym/knife4j/issues/I24ZYD)

```yml
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提供的个性化增强配置进行控制

```yml
knife4j:
	enable: true
	setting:
		# 是否显示调试Tab框架，默认为true(显示)
		enableDebug: false
```

7、解决微服务架构下，丢失basePath的问题[Gitee #I23NWM](https://gitee.com/xiaoym/knife4j/issues/I23NWM)、[Gitee #I23N6L](https://gitee.com/xiaoym/knife4j/issues/I23N6L)、[Gitee #I25ZTC](https://gitee.com/xiaoym/knife4j/issues/I25ZTC)、[GitHub #286](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/286)

8、自定义文档以及自定义Home主页的Markdown支持Html语法[Gitee #I24ZZA](https://gitee.com/xiaoym/knife4j/issues/I24ZZA)

9、去除文档右上角？号的文档显示[Gitee #I24ZYL](https://gitee.com/xiaoym/knife4j/issues/I24ZYL)

10、增强配置增加开启动态请求参数配置的配置[Gitee #I24EBO](https://gitee.com/xiaoym/knife4j/issues/I24EBO)

```yml
knife4j:
	enable: true
	setting:
		# 开启动态请求参数调试,默认为false(不开启)
		enableDynamicParameter: true
```

11、如果当前服务只有一个分组的情况下，开发者可以通过配置`enableGroup`项来控制界面的分组显示[Gitee #I25MQG](https://gitee.com/xiaoym/knife4j/issues/I25MQG)，配置如下：

```yml
knife4j:
	enable: true
	setting:
		# Ui界面不显示分组元素
		enableGroup: false
```

最终效果图如下：

![](https://xiaoym.gitee.io/knife4j/images/blog/knife4j2.0.8/groupshow.png)

12、基础类型的请求参数与响应参数示例显示优化[Gitee #I24YKT](https://gitee.com/xiaoym/knife4j/issues/I24YKT)

13、`@ApiOperationSupport`和`@DynamicParameters`注解不能同时使用的问题[Gitee #I24JWV](https://gitee.com/xiaoym/knife4j/issues/I24JWV)

14、解决V3版本中starter存在冲突的问题[Gitee #I2420J](https://gitee.com/xiaoym/knife4j/issues/I2420J)

15、优化markdown渲染的组件方式。

16、离线文档导出移除**导出PDF**项，导出pdf功能不管是基于markdown或者是word都能轻松实现，因此Knife4j废弃此功能

17、OpenAPI3结构中支持表单类型中scheme解析显示为json[Gitee #I24PCZ](https://gitee.com/xiaoym/knife4j/issues/I24PCZ)

18、针对Authorize标志的接口，添加锁的icon在接口中进行体现[Gitee #I23W0S](https://gitee.com/xiaoym/knife4j/issues/I23W0S)
![](https://xiaoym.gitee.io/knife4j/images/blog/knife4j2.0.8/authorize1.png)

![](https://xiaoym.gitee.io/knife4j/images/blog/knife4j2.0.8/authorize2.png)

19、增强配置本地缓存更新策略

20、针对禁用文档管理菜单项后，同步禁用右上角个性化菜单的显示。[Gitee #I262VN](I262VN)

21、请求OpenAPI规范实例接口默认发送一个`language`的header，如果服务端做了i18n的配置可以根据此header动态返回不同的语言释义。

21、解决根据路径设置界面i18n显示时，和服务端增强配置冲突的问题，如果开发者通过url路径来设置界面的i18n显示，则默认以路径中的为准，否则，取后端增强配置的`language`

22、菜单收缩时显示存在异常的问题[Gitee #I2646F](https://gitee.com/xiaoym/knife4j/issues/I2646F)

23、OpenAPI3规范适配支持JSR303支持[GitHub #283](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/283)

24、请求参数的数据类型为空的情况下优化，显示默认值`string`

## 使用方法

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

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

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

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

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

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

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

## Knife4jAggregation微服务聚合中间件

自`2.0.8`版本开始，Knife4j提供了轻量级的聚合微服务OpenAPI文档的中间件，可以在任意Spring Boot服务中聚合文档，最简单、最轻量级、最方便的聚合组件

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

该组件提供了4种不同的模式以满足不同语言、不同模式的方式进行OpenAPI文档的聚合

四种不同的方式：

- [Disk本地模式](https://xiaoym.gitee.io/knife4j/action/aggregation-disk.html)
- [Cloud云端接口模式](https://xiaoym.gitee.io/knife4j/action/aggregation-cloud.html)
- [Eureka注册中心模式](https://xiaoym.gitee.io/knife4j/action/aggregation-eureka.html)
- [Nacos注册中心模式](https://xiaoym.gitee.io/knife4j/action/aggregation-nacos.html)

更详细的介绍以及实战使用方法请参考[文档](https://xiaoym.gitee.io/knife4j/documentation/knife4jAggregation.html)

最后提交信息为： !34 Knife4j 2.0.8发布,轻量级微服务聚合文档中间件诞生

v2.0.7

a192f1b

2020-11-02 10:59

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

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

![](https://oscimg.oschina.net/oscnet/up-3611e3a6b050682d73b0210ec19d05976b3.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;
```

效果图：

![](https://oscimg.oschina.net/oscnet/up-e3a7a2c712a9e57875979288924b0a3ed64.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: 实体类列表
```

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

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

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

![](https://oscimg.oschina.net/oscnet/up-66d46dc15e3a7a128566f7aca736c3bb83f.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
```

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

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

## 使用方法

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

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

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

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

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

最后提交信息为： !31 3.0.1 RELEASED

v2.0.6

107a712

2020-10-26 11:50

Knife4j 2.0.6发布,支持OpenAPI3及Auth2认证

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

**关键词**：**OpenAPI3**、**Auth2.0**、**AfterScript**、**Springfox3.0**、**增强改善**

**文档**：[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

## 特性 & 优化

**2.0.6**是继续在上个版本中进行迭代更新,开发者使用OpenAPI2的结构可以直接修改版本号即可进行升级,springfox框架升级到`2.10.5`

> springfox 2.10.5 版本变化：
>
> 1、spring-plugin组件升级到2.0.0，移除了guava包
>
> 2、@EnableSwagger2注解升级为@EnableSwagger2WebMvc

Maven引用：

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

1、**OAuth2认证功能的支持:简化模式(implicit)、授权码模式(authorization_code)、密码模式(password)、客户端模式(client_credentials)**,详细规则请[参考文档](https://doc.xiaominfo.com/knife4j/OAuth2.html)

2、针对`@RequestBody`注解标注的请求实体类，在接口请求参数时是否必须(`require`)的显示异常的问题[Gitee #I1VBGB](https://gitee.com/xiaoym/knife4j/issues/I1VBGB)、[Gitee #I1YK2Q](https://gitee.com/xiaoym/knife4j/issues/I1YK2Q)、[Gitee #I1WCMF](https://gitee.com/xiaoym/knife4j/issues/I1WCMF)、[Gitee #I1VDSH](https://gitee.com/xiaoym/knife4j/issues/I1VDSH)、[GitHub #277](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/277)

3、针对服务端指定`consumes`的情况优化，如果服务端不指定,Ui会默认根据参数类型进行适配[Gitee #I1VE25](https://gitee.com/xiaoym/knife4j/issues/I1VE25)

4、解决在创建`Docket`对象时赋予`Host`属性后,文档界面显示接口地址异常的问题[Gitee #I1XYG9](https://gitee.com/xiaoym/knife4j/issues/I1XYG9)

5、微服务网关聚合文档时,自定义分组名称导致增强失败的问题[Gitee #I1Y79W](https://gitee.com/xiaoym/knife4j/issues/I1Y79W)

6、针对`query`类型的参数，如果该参数是schema类型,解析该schema为json提作为请求值.[Gitee #I1VLHH](https://gitee.com/xiaoym/knife4j/issues/I1VLHH),如下图：

7、调试栏新增`AfterScript`特性,开发者可根据`Knife4j`定义的全局变量编写自定义`JavaScript`脚本,增强接口交互体验[Gitee #I1YNU3](https://gitee.com/xiaoym/knife4j/issues/I1YNU3)、[Gitee #I1CAAD](https://gitee.com/xiaoym/knife4j/issues/I1CAAD),关于`AfterScript`特性可参考[文档](https://doc.xiaominfo.com/knife4j/afterScript.html)

主要应用场景：

- 针对JWT类型的接口,调用登录接口后,每个接口请求时带上Token参数,此时可以通过该脚本动态赋值全局token参数,省去复制粘贴的麻烦.

假设某一个登录接口响应的JSON内容如下：

```json
{
  "code": 8200,
  "message": null,
  "data": {
    "token": "1y1tn8tvw93fxixp79dcx0nugixkw4su"
  }
}
```

该接口是登录接口,除该接口外其余接口请求都需要带上`token`的请求头,因此我们访问登录接口后,设置全局Header参数`token`,此操作`Knife4j`接下来会为每一个请求接口带上`token`参数，代码如下：

```javascript
var code=response.data.code;
if(code==8200){
    //判断,如果服务端响应code是8200才执行操作
    //获取token
    var token=response.data.data.token;
    //1、如何参数是Header，则设置全局Header
    ke.global.setHeader("token",token);
}
```

8、通过创建Docket对象时设置`globalOperationParameters`全局参数时,针对`header`类型的`allowableValues`不支持下拉框选择的问题[Gitee #I1OC0H](https://gitee.com/xiaoym/knife4j/issues/I1OC0H)

代码如下：

```java
parameters.add(new ParameterBuilder().name("header-test").description("balabala")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .allowableValues(new AllowableListValues(Arrays.asList("下拉1", "下拉2"), "string"))
                .required(false).order(1).build());
new Docket(DocumentationType.SWAGGER_2)
                .host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName("2.X版本")
                .globalOperationParameters(parameters)
```

9、离线导出功能板块增加导出OpenAPI的原始JSON格式数据，导出该逻辑分组下所有接口的OpenAPI原始json格式。如下图：

10、针对单个接口，提供OpenAPI的源码格式，可以通过复制或者下载该源码格式直接导入POSTMAN进行测试[Gitee #I1Z7AP](https://gitee.com/xiaoym/knife4j/issues/I1Z7AP)。如下图：

11、增强注解`@EnableKnfie4j`增加Spring Boot中的Conditional条件`@ConditionalOnWebApplication`,仅在Web环境下加载，避免在使用`junit`单元测试时出现异常。

12、**增强模式的改进,主要有两个变化,更加详细的使用规则**，开发者请[参考文档](https://doc.xiaominfo.com/knife4j/enhance.html)：

- 提供`spring.factories`进行自动装置,开发者可以直接在Spring Boot的配置文件`yml`或者`property`等使用属性`knife4j.enable:true`进行开启使用，配置属性后无需再使用`@EnableKnife4j`注解

- 提供`spring-configuration.meta.json`文件，对`Knife4j`提供的各个增强配置属性进行注释，方便开发者在配置文件中进行配置，如下图：

13、针对其它文档的配置，开发者可以根据每一个逻辑分组Docket进行配置，其他文档支持自定义文档的分组标题

14、接口排序需求无需再Ui界面勾选增强，只需要在配置文件中开启`knife4j.enable=true`接口，然后使用`@ApiSupport`注解或者`@ApiSort`在`Controller`类上进行使用，优先级`@ApiSupport>@ApiSort`,该方式更加融合了springfox框架的特性，也更符合对扩展属性扩展的规范，在OpenAPI结构节点增加`x-order`扩展参数，如下图：

15、移除增强扩展接口地址`/v2/api-docs-ext`,个性化配置及增强通过后端配置文件进行配置即可,通过更加规范的使用增强注解,符合OpenAPI的扩展属性规范。

16、其他文档以更加符合OpenAPI的扩展规范进行展示，开发者可以在yml配置文件中配置多个分组文档(`前提是knife4j.enable=true`),然后再创建的`Docket`对象中使用`Knife4j`提供的`OpenApiExtensionResolver`扩展`extension`,最终配置的md文件会在文档中进行分组呈现.[GitHub #115](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/115)

`application.yml`配置示例代码如下：

```yml
knife4j:
  enable: true
  documents:
    -
      group: 2.X版本
      name: 接口签名
      locations: classpath:sign/*
    -
      group: 2.X版本
      name: 另外文档分组请看这里
      locations: classpath:markdown/*
```

Java代码：

```java
@Configuration
@EnableSwagger2WebMvc
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
 
   private final OpenApiExtensionResolver openApiExtensionResolver;

@Autowired
    public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }
    
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName="2.X版本";
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
            //此处调用openApiExtensionResolver的方法获取extensions集合
                .extensions(openApiExtensionResolver.buildExtensions(groupName))
                .securityContexts(CollectionUtil.newArrayList(securityContext())).securitySchemes(CollectionUtil.newArrayList(apiKey()));
        return docket;
    }
}
```

17、针对使用`@ApiModelProperty`注解，给予实体String类型的属性字段赋值`example`示例值json字符串时显示异常的问题[GitHub #233](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/233)

18、请求示例和响应示例中的长整形精度丢失的问题[GitHub #269](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/269)

19、针对当前接口存在Authorze认证情况下，没有点击该功能时参数不会默认在接口调试中的Bug以及query类型参数始终出现在请求头参数栏的情况[Gitee #I1VC4I](https://gitee.com/xiaoym/knife4j/issues/I1VC4I)

20、去除Ui界面中个性化设置中的启用增强配置。

21、增强注解`@ApiOperationSupport`与`@DynamicResponseParameters`同时使用时,动态响应字段丢失的问题[Gitee #I22K0R](https://gitee.com/xiaoym/knife4j/issues/I22K0R)

22、离线文档下载失败的问题，变量引用错误导致[Gitee #I1W5UB](https://gitee.com/xiaoym/knife4j/issues/I1W5UB)

## OpenAPI3

如果开发者想使用springfox的OpenAPI3的版本,Knife4j此次发布了两个版本,针对3.0版本,Knife4j底层升级springfox组件到`springfox3.0.0`,并且版本号从`3.x`系列开始,代表OpenAPI3,以区分`2.x`系列。

Maven引用

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

针对SpringFox3.0的版本,作者在开发过程中虽然在Ui上对OpenAPI3进行了支持,但是目前springfox3.0还存在诸多的问题，建议开发者慎重使用springfox3。不管是对于OpenApi2以及OpenApi3的支持，目前springfox3在兼容性等方面都存在一些问题,毕竟刚发布一个版本.

相对而言,springfox2.x系列的版本较稳定.当Springfox对于3.0的结构相对稳定后,Knife4j的主分支版本会向3.0靠拢。

相关ISSUES:

- [#I1UGH7 swagger 2.9.2 对 javax.validation 支持缺少，可考虑升级到 2.10.5](https://gitee.com/xiaoym/knife4j/issues/I1UGH7)
- [#I1R9J1 关于支持 Springfox Swagger 3.0.0](https://gitee.com/xiaoym/knife4j/issues/I1R9J1)
- [#I1VYDM 早日支持下springfox-boot-starter 3.0](https://gitee.com/xiaoym/knife4j/issues/I1VYDM)
- [#I1X27Y swagger 升级到3.0后的兼容问题](https://gitee.com/xiaoym/knife4j/issues/I1X27Y)
- [#I1QQYH knife4j-vue-v3 setInstanceBasicPorperties 方法中逻辑问题](https://gitee.com/xiaoym/knife4j/issues/I1QQYH)
- [#275 springfox-3.0.0与knife4j-2.0.5冲突？](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/275)
- [#268 spring boot 2.3.3、springfox 3.0.0与knife4j2.0.4集成报错问题](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/268)
- [#265 spring-plugin-core的兼容问题](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/265)

最后提交信息为： !27 3.0 merge

v2.0.5

6223dda

2020-09-15 09:53

Knife4j 2.0.5版本发布,性能优化

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

Gitee：https://gitee.com/xiaoym/knife4j

GitHub：https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性 & 优化

1、Ui整体性能优化,主要从以下几个方面展开Gitee #I1TYNK、Gitee #I1LWNM、Gitee #I1J52C、GitHub #243

- 获取接口初始化Swagger文档时,只初始化菜单、以及基础信息字段
- 接口path节点以及Model-definition节点作为异步解析，除了导出功能外只有展示的文档涉及到的信息才会进行解析，缩减没必要的内存开销和空间性能等待
- SwaggerModels功能中的所有Model通过异步加载,减少内存开销.

2、通过@EnableKnife4j注解注入的实体Bean包含部分Filter,Filter涉及到应用入侵,优化为只有在开发者启用了Knife4j提供的配置值时,该实体Bean才生效

3、解决通过/plus路径来开启增强模式时失效的问题Gitee #I1OJCK

4、接口描述信息支持Markdown语法渲染

5、解决调试发送后,状态栏curl出现参数为null的问题Gitee #I1QC7Z、Gtiee #I1QXJ1

6、移除fastjson等不必要的依赖Gitee I1OIY9

7、在左侧菜单接口中新增接口类型,并且在分组中显示当前分组下包含的接口数量Gitee #I1PE0H，如下图：

8、优化在当前分组名称/Controller名称/接口分词中带字符/导致页面空白的问题,如果包含使用字符-进行替换Gitee #I1SMAY

9、Vue以及ant-design-vue版本升级到当前最新版

10、导出的离线Html文档优化属性,去除无效的属性引用导致Html文档文件太大(降低5倍以上).

11、增加导出Word文档的实现

12、返回大数据量造成页面卡死的问题优化Gitee #I1QIJK

13、优化默认的标题显示,开发者未设置分组服务标题时文档标题默认显示Knife4j 接口文档Gitee #I1P4OQ

14、枚举类型针对Array数组类型支持多选Gitee #I1NOTE、GitHub #267

15、针对POST、PUT、PATCH等请求方式,以x-www-form-urlencoded请求头发送请求时,请求参数在url追加的问题,以避免请求时400错误的发生.

16、在i18n环境下离线文档导出时没有完全国际化的优化操作Gitee #I1MKP7

17、针对@RequestBody的请求下载接口响应乱码的问题修复Gitee I1U4LA

18、调试返回状态栏数据大小的显示优化B.KB、MBGitHub #264

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

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

20、接口文档中针对请求参数存在示例值的情况下,在接口的参数说明中予以显示GitHub #109

21、去除doc.html对favicon.ico的请求,以避免开发者在网关微服务的架构中集成时出现404.

最后提交信息为： !25 2.0.5 RELEASED

v2.0.4

fa5419c

2020-06-28 12:40

Knife4j 2.0.4 版本发布，支持自定义 Host

`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、支持UiConfiguration中方法调试的配置,如并未配置任何支持的方法,在ui界面中不会出现调试栏Tab，代码如下：

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

2、在当前文档页添加`复制接口`功能，便于开发人员快速复制接口地址[github #238](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/238)

3、修复Authorize修改或注销的问题[gitee #I1IJK3](https://gitee.com/xiaoym/knife4j/issues/I1IJK3)

4、个性化配置新增Host属性的配置,如果当前对外提供的接口文档和接口本身Host属性存在冲突,可以自动配置此属性进行接口的联调，Host属性可以配置为`ip:port`的形式，这样默认是HTTP进行访问,开发者也可以配置完整的域名或者`HTTPS`等配置

其工作原理是在调用axios组件进行接口调试时,配置其`baseURL`属性

```javascript
var baseUrl='';//默认是空
//是否启用Host
if(this.enableHost){
    baseUrl=this.enableHostText;
}
var requestConfig={
    baseURL:baseUrl,//调用目标Host服务的接口
    url: url,
    method: methodType,
    headers: headers,
    params: formParams,
    data: data,
    //Cookie标志
    withCredentials:this.debugSendHasCookie(headers),
    timeout: 0
}
```

开发者要使用此Host的配置后端必须开启跨域的配置，如果是`Spring Boot`，示例代码如下：

```java
@Bean
public CorsFilter corsFilter(){
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration corsConfiguration=new CorsConfiguration();
    corsConfiguration.setAllowCredentials(true);
    corsConfiguration.addAllowedOrigin("*");
    corsConfiguration.addAllowedHeader("*");
    corsConfiguration.addAllowedMethod("*");
    corsConfiguration.setMaxAge(10000L);
    source.registerCorsConfiguration("/**",corsConfiguration);
    CorsFilter corsFilter=new CorsFilter(source);
    return corsFilter;
}
```

5、调试接口时,接口在无返回数据或者异常的情况下弹框错误信息,提示开发者

6、图片预览接口无法在响应内容中在线预览图片的问题[gitee #I1KP0Q](https://gitee.com/xiaoym/knife4j/issues/I1KP0Q)

7、修复针对`Map`字段时,Value指引是本类时出现递归死循环的问题,结构如下：

```json
"SensorTable": {
            "type": "object",
            "properties": {
                "attrib": {
                    "type": "integer",
                    "format": "int32"
                },
                "sensorMap": {
                    "type": "object",
                    "additionalProperties": {
                        "originalRef": "SensorTable",
                        "$ref": "#/definitions/SensorTable"
                    }
                }
                //more...
            },
            "title": "SensorTable"
        },
```

8、修复离线文档功能导出`Markdown`时,响应参数格式异常的问题[gitee #I1LMYO](https://gitee.com/xiaoym/knife4j/issues/I1LMYO)

9、修复在使用中间件对接口响应内容进行拦截处理时,响应内容不显示的bug，例如使用`sentinel `进行QPS限流,一般在这种情况下是由于接口响应的Content-Type是json，但实际响应内容却是text导致[gitee #I1JO73](https://gitee.com/xiaoym/knife4j/issues/I1JO73)

最后提交信息为： 2.0.4 RELEASED

v2.0.3

086ab63

2020-05-24 16:10

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();
}
```

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

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)

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框架的集成支持

如果你后端是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)

最后提交信息为： 2.0.3 RELEASED

v2.0.2

454f903

2020-03-08 19:55

Knife4j 2.0.2正式发布,Swagger接口文档赋能工具

`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、新增`knife4j-dependencies`模块,管理knife4j的相关Maven引用,可以以Maven的BOM方式引入`Knife4j`

2、[官网](http://doc.xiaominfo.com/)文档同步更新.

3、解决`swagger-annotations`导致的版本冲突[gitee #I17G31](https://gitee.com/xiaoym/knife4j/issues/I17G31)、[GitHub #191](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/191)

### knife4j-spring-ui

1、修复切换tab之后 再次发送请求不带参数且不显示响应数据的问题，调试异常等问题[PR 13 @gitee](https://gitee.com/xiaoym/knife4j/pulls/13)、[gitee #I17FFX](https://gitee.com/xiaoym/knife4j/issues/I17FFX)、[GitHub #196](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/196)、[GitHub #187](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/187)

2、优化调试框全部选中的问题,在取消全选时,只有在输入参数改变时才会选中该参数,取消原来默认选中全部参数[gitee #I19V6D](https://gitee.com/xiaoym/knife4j/issues/I19V6D)

3、针对Form表单类型的请求构造curl命令行时在未输入值的情况下为null的情况,修改为空字符串[gitee #I18IBZ](https://gitee.com/xiaoym/knife4j/issues/I18IBZ)

4、优化全局参数设置功能,针对参数数据太长不换行问题，以及参数需要修改时需要重新删除的交互体验，开发者在新增参数后可以方便的更改参数数据值以及参数的类型[gitee #I17OV1](https://gitee.com/xiaoym/knife4j/issues/I17OV1)、[gitee #I19GJK](https://gitee.com/xiaoym/knife4j/issues/I19GJK)、[gitee #I1A9V1](https://gitee.com/xiaoym/knife4j/issues/I1A9V1)、[gitee #I18HMJ](https://gitee.com/xiaoym/knife4j/issues/I18HMJ)、[GitHub #176](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/176)

5、请求参数在未给定example默认值的情况下,文本输入框的placeHolder属性显示该字段的文字说明[gitee #I17RKI](https://gitee.com/xiaoym/knife4j/issues/I17RKI)

6、修复增强属性忽略参数不生效的问题[gitee #PR-16](https://gitee.com/xiaoym/knife4j/pulls/16)、[gitee #I136KU](https://gitee.com/xiaoym/knife4j/issues/I136KU)、[gitee #I187VN](https://gitee.com/xiaoym/knife4j/issues/I187VN)、[gitee #I16A71](https://gitee.com/xiaoym/knife4j/issues/I16A71)

7、调试参数框增加对后端枚举的支持,改输入框为下拉选择框[gitee #I18MHO](https://gitee.com/xiaoym/knife4j/issues/I18MHO)

8、service-worker.js报404问题，构建打包时添加此文件[gitee #I17D0Y](https://gitee.com/xiaoym/knife4j/issues/I17D0Y)、[GitHub #185](https://github.com/xiaoymin/swagger-bootstrap-ui/issues/185)

9、get请求参数出现特殊字符未编码处理导致出现400错误[gitee #I19C8Y](https://gitee.com/xiaoym/knife4j/issues/I19C8Y)

10、后端新增接口或者接口编辑后,在ui界面显示更新标志,在菜单上会出现一个蓝色的徽标[gitee #I1AQFW](https://gitee.com/xiaoym/knife4j/issues/I1AQFW)，如下图:

11、后端增强注解`@ApiOperationSupport(author = "xiaoymin@foxmail.com")`支持每个接口提供开发者的呈现,最终如下图：

12、调试发送按钮增加`loading`效果,针对接口响应较长的情况下提升交互效果

13、针对Authorize菜单栏的参数,保存参数是全局保存,其它逻辑分组的接口再调试时,不需要再保存一次新值[gitee #I16Z10](https://gitee.com/xiaoym/knife4j/issues/I16Z10)

14、修复部分情况响应字段在ace-editor编辑器右边栏不显示字段说明的情况[gitee #I17F5Y](https://gitee.com/xiaoym/knife4j/issues/I17F5Y)

15、搜索框完善对接口请求Api地址栏的模糊搜索匹配[gitee #I19EN0](https://gitee.com/xiaoym/knife4j/issues/I19EN0)、[gitee #I1B0Q9](https://gitee.com/xiaoym/knife4j/issues/I1B0Q9)

16、调试响应数据行太长,无法换行的问题[gitee #I17F1J](https://gitee.com/xiaoym/knife4j/issues/I17F1J)

17、在当前接口无参数的情况下,界面添加全局参数无效果的bug

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

```xml
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>2.0.2</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.2</version>
</dependency>
```

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

```

## 特点

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

最后提交信息为： 2.0.2 RELEASED

v2.0.1

a091b53

2019-12-23 10:08

Knife4j 2.0.1发布,细节处理！

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

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

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

**效果(2.0版):**[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-spring-ui

1、解决`x-www-form-urlencoded`类型的表单请求，参数勾选复选框无法取消的情况[gitee #I16S14](https://gitee.com/xiaoym/knife4j/issues/I16S14)

2、个性化配置中新增是否开启动态参数选项,默认为`false`，不开启,如果有需要的可以勾选此选项,可以无限动态添加参数进行接口调试

3、实现全局搜索功能[gitee #I16ZW4](https://gitee.com/xiaoym/knife4j/issues/I16ZW4)

4、@Deprecated 标记的接口置为过时[gitee #I1736T](https://gitee.com/xiaoym/knife4j/issues/I1736T)

5、针对返回的数据太大,导致页面卡死的情况下,界面做限制处理，如果返回的数据大于2M，不进行格式化处理，弹出提示,提醒开发者在raw进行响应内容的查看,只显示纯文本[gitee #I16ZV4](https://gitee.com/xiaoym/knife4j/issues/I16ZV4)

6、优化响应数据大小的格式化显示,BYTE\KB\MB

7、实现图片预览功能[gitee #I173AN](https://gitee.com/xiaoym/knife4j/issues/I173AN)

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

```xml
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>2.0.1</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.1</version>
</dependency>
```

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

```

最后提交信息为： 2.0.1 RELEASED

v2.0.0

312893e

2019-12-16 09:39

Knife4j 2.0发布,涅槃重生~！

Knife4j前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.虽然目前还只是在前端，但以后功能肯定不止于此.

2.0版本主要是使用Vue+Ant Design Vue对前端Ui进行重写,该版本是真正的前后端分离版本，同时依赖于Vue的技术生态,以后会有更多有趣的功能实现,全方位满足开发者的需要.

文档：http://doc.xiaominfo.com

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

效果(2.0版):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-spring-ui

1、使用Vue+Ant Design Vue对Ui进行重写,统一整体界面风格,更清晰的文档说明能力以及接口调试能力

2、支持在界面中导出离线Markdown、离线Html格式的文档，Markdown、Html风格较之前都做了极致的优化，Markdown格式主要是针对树形Model的展示通过缩进的方式在md格式的table中显示更加直观,Html离线文档和在线版风格几乎没有区别，简洁、直观.点击预览导出离线Html效果

3、单接口文档页的复制文档也是通过复制Markdown格式的问题，同上主要优化md格式的table显示问题，以缩进的方式显示树形表格

4、对调试栏进行优化、区分请求头和请求体参数,使用tab标签页组件可以对请求参数进行动态的添加、维护、如果你使用对文档进行缓存,文档页的动态调试参数会持久化处理.

5、文档的个性化配置(增强功能)有删减,目前只保留4项功能，即(请求参数缓存、过滤重复同类型接口、本地缓存打开tab接口、文档增强)

6、Tab标签页打开接口、右键可以根据选择关闭不同的Tab标签页

7、调试框请求头、请求体均支持动态参数，开发者可以自行添加动态参数进行调试,更加灵活方便

8、提供增强直接访问地址，http://ip:port/doc.html#/plus，后端在保证开启增强注解的情况下可直接使用该地址,不需要在前端个性化配置中再进行配置,方便团队直接进行沟通

9、响应下载类型增加至141种,几乎涵盖目前常见的文件类型

10、修复响应体中会出现属性多余双引号的buggitee # I125B2、github #156

11、修复请求参数数据类型的format不显示的问题,针对Long类型区分int64、int32- github #161

12、解决多个Schema响应状态码的情况下SwaggerModels字段不显示的问题github #170

13、调试请求默认追加一个Ui的请求头Request-Origion,值为Knife4j，原来该值是SwaggerBootsrapUi，在2.0版本中进行了变更.

14、解决Models属性嵌套过多时,页面白板，效率问题github #106

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

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

Knife4j-Spring

1、移除增强注解@EnableSwaggerBootstrapUi,以后的增强开启注解请使用@EnableKnife4j

2、knife4j-spring-boot-starter组件移除默认springfox的ui-jar包springfox-swagger-ui,只保留knife4j-spring-ui,开发者如果要使用springfox的ui包需要自行在项目中引入

3、合并PR12-修复IDEA debug无法显示动态Response的问题,修复动态类加载不到的问题

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

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

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

特点

最后提交信息为：效果图

v1.9.6

3d52a11

2019-08-29 10:05

swagger-bootstrap-ui 1.9.6 发布，解决长整型精度丢失的问题

swagger-bootstrap-ui 1.9.6 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现，使文档更友好一点儿

文档：http://doc.xiaominfo.com

效果：http://swagger-bootstrap-ui.xiaominfo.com/doc.html

Gitee:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

## 重要说明

**这是swagger-bootstrap-ui的最后一个版本**

重要的事情说三遍!!!

一开始项目初衷是为了写一个增强版本的Swagger 前端UI,但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端Java代码以满足新的需求,在swagger-bootstrap-ui的1.8.5~1.9.6版本之间,采用的是后端Java代码和Ui都混合在一个Jar包里面的方式提供给开发者使用.这种方式虽说对于集成swagger来说很方便,只需要引入jar包即可,但是在微服务架构下显得有些臃肿。

因此,项目正式更名为knife4j,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端.

swagger-bootstrap-ui的所有特性都会集中在knife4j-spring-ui包中,并且后续也会满足开发者更多的个性化需求.

主要的变化是,项目的相关类包路径更换为com.github.xiaoymin.knife4j前缀,开发者使用增强注解时需要替换包路径

后端Java代码和ui包分离为多个模块的jar包,以面对在目前微服务架构下,更加方便的使用增强文档注解(使用SpringCloud微服务项目,只需要在网关层集成UI的jar包即可,因此分离前后端)

knife4j沿用swagger-bootstrap-ui的版本号,第1个版本从1.9.6开始,关于使用方法,请参考文档

由于更名给大家带来的不便深表歉意~！

## 特性&优化

1、解决Spring路由PathVariable不显示的情况，并优化交互体验

2、解决响应体中的长整型显示错误,精度丢失的问题#135 @GitHub

3、优化请求头Header是中文的情况,如果包含中文则进行encodeURI函数处理,否则不做任何处理#140 @GitHub

4、升级jQuery 1.X系列版本到最新版本1.12.4

5、初始化页面请求Swagger接口资源方式改为异步,在jQuery的ajax方法参数项async:false时,浏览器会抛出警告的问题(同步ajax请求会造成主线程阻塞,对用户体验不是很好,已被置为过时).

6、支持supportedSubmitMethods,后端配置UiConfiguration的Bean#IVCQ0 @Gitee

7、优化下载中文乱码问题,后端需要指定filename值,并且对名称进行URLEncoder.encode处理,UI前端会进行decode成中文,保证下载正常

8、修复curl状态栏复制时内容被转义的bug#136 @GitHub

## Maven坐标

<dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>swagger-bootstrap-ui</artifactId>
       <version>1.9.6</version>
    </dependency>

最后提交信息为： maven配置不规范,添加name、url属性值

v1.9.5

7b671f1

2019-07-31 21:13

swagger-bootstrap-ui 1.9.5 发布，支持过滤请求参数

swagger-bootstrap-ui 1.9.5 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现，使文档更友好一点儿

文档：http://doc.xiaominfo.com

效果：http://swagger-bootstrap-ui.xiaominfo.com/doc.html

Gitee:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性&优化

1、针对文件上传响应JSON内容时,内容不高亮的问题#IYXZB @Gitee

2、文件上传响应内容显示异常Bug#IYO96 @Gitee

3、针对中文请求头使用encodeURIComponent()函数进行编码处理#IYMUF @Gitee

4、修复开启增强时空指针异常Bug#IYADU @Gitee

5、针对@ResponseHeader注解未显示Bug#IY86A @Gitee

6、DELETE请求针对Array类型的请求参数错误Bug#IY37Z @Gitee

7、修复GET请求时CURL响应栏参数拼装错误#131 @GitHub

8、修复非200状态码响应内容不格式化高亮的问题#130 @GitHub

9、解决地址显示的BUG, 确保请求能够正确发送出去#PR108 @GitHub

10、在使用动态扩展字段说明时,服务器上部署会造成空指针异常,该错误是由未对field名称进行非空判断导致#IYLVC @Gitee、#119 @GitHub

11、可以自定义动态过滤请求参数,这在很多时候可以让我少写实体类，比如新增的时候不需要id，修改时又需要id，只需要在接口层使用增强注解@ApiOperationSupport的ignoreParameters属性即可,具体使用规则请参考文档

12、优化增强排序接口注解@ApiSort无效果的问题

13、响应类Model动态添加解释字段.请参考文档

Maven坐标

<dependency>
       <groupId>com.github.xiaoymin</groupId>
       <artifactId>swagger-bootstrap-ui</artifactId>
       <version>1.9.5</version>
    </dependency>

最后提交信息为： 1.9.5 RELEASED

v1.9.4

cb36f3e

2019-06-10 17:14

swagger-bootstrap-ui 1.9.4 发布，扩展支持动态字段注释

swagger-bootstrap-ui 1.9.4 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现，使文档更友好一点儿

文档：http://doc.xiaominfo.com

效果：http://swagger-bootstrap-ui.xiaominfo.com/doc.html

Gitee:https://gitee.com/xiaoym/swagger-bootstrap-ui

GitHub:https://github.com/xiaoymin/swagger-bootstrap-ui

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

特性&优化

1、最低需要JDK 1.8支持

2、单独接口通过hash地址访问,方便开发人员之间快速复制传递接口信息,能准确定位到接口

3、优化下载参数名称问题,忽略filename大小写敏感#IXA5C @Gitee

4、优化BasicFilter过滤器正则匹配频率问题,decode函数调用替换为JDK 1.8版本中的java.util.Base64

5、tab操作项修改为点击事件显示,避免同调试按钮冲突导致误关选项卡#IXA5I @Gitee

6、增加调试接口响应类型为Xml、Html、Text的支持#IWP49 @Gitee

7、优化调试后header、raw、curl等选项卡高度太低的问题#IWLSU @Gitee

8、主页简介description字段支持markdown格式#IVVRX @Gitee

9、针对枚举类型的集合类型(List),在字段描述中显示枚举可用列表值#100 @GitHub

10、重构原接口排序、tag排序规则,新增接口作者属性,可写每个接口的作者,方便开发者调试.参考文档

11、针对Authorize授权的相关属性,不同分组相同的请求参数只需授权一次即可则全局通用#IXHBL @Gitee

12、针对Map、JSONObject等动态类型可通过自定义注解@ApiOperationSupport或者@DynamicParameters来增加参数的字段说明,解决不想写实体类的烦恼,但是又无文档的困扰.参考文档

13、优化自定义文档(markdown)界面效果,增加相关markdown语法样式(引用editormd.css)

最后提交信息为： 1.9.4 RELEASED 完善相关类JavaDoc注释

v1.9.3

e8b2c8a

2019-04-23 16:50

swagger-bootstrap-ui 1.9.3 发布，i18n及自定义文档支持

最后提交信息为： 1.9.3.RELEASED

GVP萧明/knife4j

搜索帮助

GVP 萧明/knife4j