24 Knife4j 2.0.3发布,支持springdoc和i18n]

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

# 特性 & 优化

# knife4j

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

# knife4j-spring-ui

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

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

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

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

3、GET请求出现参数未填的情况下发送Null的buggitee #I1BG4O (opens new window)、github #213 (opens new window)

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

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

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

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

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

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

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

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

12、剔除webjar文件中的favicon.ico文件,以避免和主项目产生冲突gitee #I1ELHN (opens new window)、github #215 (opens new window)

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

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

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

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

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

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

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

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

21、添加对springdoc框架的集成支持，非常感谢teddygong (opens new window)提交的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>