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

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

# 特性 & 优化

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

2、增加自定义主页的增强配置，开发者可以提供一个Markdown文档，用来自定义Home主页显示的内容Gitee #I24ZXI (opens new window)

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

3、OpenAPI开放接口可以通过增强配置是否显示Gitee #I25273 (opens new window)

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

4、搜索框可以通过增强配置是否显示Gitee #I24ZYY (opens new window)

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

5、文档最下边的footerkey通过增强配置是否显示，并且可以自定义显示内容Gitee #I24ZYD (opens new window)

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

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

7、解决微服务架构下，丢失basePath的问题Gitee #I23NWM (opens new window)、Gitee #I23N6L (opens new window)、Gitee #I25ZTC (opens new window)、GitHub #286 (opens new window)

8、自定义文档以及自定义Home主页的Markdown支持Html语法Gitee #I24ZZA (opens new window)

9、去除文档右上角？号的文档显示Gitee #I24ZYL (opens new window)

10、增强配置增加开启动态请求参数配置的配置Gitee #I24EBO (opens new window)

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

11、如果当前服务只有一个分组的情况下，开发者可以通过配置enableGroup项来控制界面的分组显示Gitee #I25MQG (opens new window)，配置如下：

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

最终效果图如下：

12、基础类型的请求参数与响应参数示例显示优化Gitee #I24YKT (opens new window)

13、@ApiOperationSupport和@DynamicParameters注解不能同时使用的问题Gitee #I24JWV (opens new window)

14、解决V3版本中starter存在冲突的问题Gitee #I2420J (opens new window)

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

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

17、OpenAPI3结构中支持表单类型中scheme解析显示为jsonGitee #I24PCZ (opens new window)

18、针对Authorize标志的接口，添加锁的icon在接口中进行体现Gitee #I23W0S (opens new window)

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

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

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

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

22、菜单收缩时显示存在异常的问题Gitee #I2646F (opens new window)

23、OpenAPI3规范适配支持JSR303支持GitHub #283 (opens new window)

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

# 使用方法

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.8</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.2</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.2</version>
</dependency>

# Knife4jAggregation微服务聚合中间件

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

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