Swagger Bootstrap Ui Versions Save

Knife4j is a set of Swagger2 and OpenAPI3 All-in-one enhancement solution

v4.0.0

1 year ago

for details: https://doc.xiaominfo.com/docs/changelog/x/4.0

2.0.9

2 years ago

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

文档：https://xiaoym.gitee.io/knife4j/

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

日志

OpenAPI3

1、在OpenAPI3.0规范中针对下载请求对象显示错误的优化Gitee#I374SP

2、针对OpenAPI3规范中对于binary类型的format属性，上传组件不显示的问题Gitee#I34NOS、Gitee #I3BRWT

3、OpenAPI3.0规范中Swagger models 中的枚举显示PR #43、Gitee #I3DP8P

4、针对OpenAPI3.0规范权限拦截问题增加接口地址Gitee #I2810R、Gitee #I3HSK4

5、针对OpenAPI3规范支持请求参数中包含$ref的问题Gitee #I2A89C

6、针对OpenAPI3规范中图片预览的问题优化Gitee #I3IUUQ

聚合组件aggregation

1、聚合组件针对Cloud模式转发HTTP请求时，请求头重复导致转发失败的问题Gitee #PR39

2、aggregation聚合组件增加order属性，方便开发者排序设置聚合OpenAPI文档的顺序Gitee #I27ST2

3、aggregation聚合组件Nacos聚合微服务文档支持Nacos用户名及密码访问OpenAPI接口Gitee #I28IF9

4、聚合组件日志打印信息优化，增加isDebugEnabled逻辑判断,日志级别全部由info改为debug级别Gitee #I39QPL

5、聚合组件响应Model不显示的问题Gitee #I3EMZE

6、聚合组件没有正确响应接口的状态码信息PR #44

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

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

8、聚合组件转发文件时参数丢失的问题Gitee #I39OXE

常规

1、OAuth2授权Content-Type的异常问题Gitee#PR35、Gitee#I2CKHA

2、OAuth2判断异常的问题Gitee #PR37

3、修复离线导出Markdown文档自定义文档为undefined的问题Gitee#I2EDI8、Gitee #I2WCQG

4、日志的打印优化Gitee #I39QPL

5、微服务聚合时basePath不追加的问题Gitee #I3B5BK、Gitee #I3EEJ3

6、针对List类型示例值多出换行符的问题Gitee #I2D6D4

7、解决Form类型上传参数时传递Null的问题Gitee #I3AHDQ

8、针对个性化配置的保存问题修改逻辑，开发者通过界面保存个性化配置后丢失的问题Gitee #I27CN8、Gitee #I2CBZQ、Gitee #I2978Y、Gitee #I3IEXT、Gitee #I3Q0MO、Gitee #I3QSAN

9、针对接口分组中不存在API接口时出现链接点击空白的问题处理，如果分组下没有API接口,默认点击显示主页Gitee #I2CVTF

10、OpenAPI规范中tags缺失时导致接口不显示的问题优化,增加default默认分组Gitee #I27M98

11、针对服务端使用@RequestMapping注解通过method限定方法类型时，Ui增强功能过滤不生效的问题Gitee #I28RJ5

12、文件上传类型接口请求数据显示类型错误的情况改进，根据参数设置接口请求数据类型为multipart/form-dataGitee #I29KMH

13、优化响应html/xml/text等内容时展现方式Gitee #I2A0QA

14、分组下拉框搜索失效的问题Gitee #I3BAOK

15、优化OpenAPI版本判断的逻辑,根据响应OpenAPI规范JSON再判断获取当前的规范版本，防止出现空异常或Model不显示等问题Gitee #I37X0Q、Gitee #I3EMZE

16、针对JSON请求格式的提交，增加Beantify按钮，可以对文本格式化美化的功能Gitee #I39MUP

17、调试发送时增强loading效果体验Gitee #I3BG5V

18、SwaggerModels 内容太长不会自动换行的问题Gitee #I3QC02

19、针对Map属性的结构展示异常的问题Gitee #I37WB7

20、解决afterScript特性不能添加多个参数的问题Gitee #I3OJUW

21、优化响应内容判断base64导致效率低下的问题Gitee #I2VRD5。

22、针对增强注解@ApiOperationSupport提供的ignoreParameters属性提供正则模式的忽略策略支持Gitee #I21ZKC

2.0.8

3 years ago

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

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

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

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

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

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

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

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

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、Gitee #I23N6L、Gitee #I25ZTC、GitHub #286

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

9、去除文档右上角？号的文档显示Gitee #I24ZYL

10、增强配置增加开启动态请求参数配置的配置Gitee #I24EBO

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

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

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

最终效果图如下：

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

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

14、解决V3版本中starter存在冲突的问题Gitee #I2420J

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

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

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

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

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

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

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

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

22、菜单收缩时显示存在异常的问题Gitee #I2646F

23、OpenAPI3规范适配支持JSR303支持GitHub #283

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>

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

四种不同的方式：

更详细的介绍以及实战使用方法请参考文档

2.0.7

3 years ago

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、服务端创建Docket对象时配置globalOperationParameters参数时,header类型不选中或丢失的问题

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

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

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

5、字段参数说明支持html标签样式。Gitee #I22RZ2

示例代码：

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

效果图：

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

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

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

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

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

knife4j:
  enable: true
  setting:
    enableAfterScript: false

9、支持@RequestMapping注解中的params参数Gitee #I22J5Q

10、3.0版本不支持Authorize的问题Gitee #I22WVM

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

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>

2.0.6

3 years ago

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

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

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

特性 & 优化

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

springfox 2.10.5 版本变化：

1、spring-plugin组件升级到2.0.0，移除了guava包

2、@EnableSwagger2注解升级为@EnableSwagger2WebMvc

Maven引用：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--OpenAPI2.0的开发者继续使用Knife4j 2.x系列的版本-->
    <version>2.0.6</version>
</dependency>

1、OAuth2认证功能的支持:简化模式(implicit)、授权码模式(authorization_code)、密码模式(password)、客户端模式(client_credentials),详细规则请参考文档

2、针对@RequestBody注解标注的请求实体类，在接口请求参数时是否必须(require)的显示异常的问题Gitee #I1VBGB、Gitee #I1YK2Q、Gitee #I1WCMF、Gitee #I1VDSH、GitHub #277

3、针对服务端指定consumes的情况优化，如果服务端不指定,Ui会默认根据参数类型进行适配Gitee #I1VE25

4、解决在创建Docket对象时赋予Host属性后,文档界面显示接口地址异常的问题Gitee #I1XYG9

5、微服务网关聚合文档时,自定义分组名称导致增强失败的问题Gitee #I1Y79W

6、针对query类型的参数，如果该参数是schema类型,解析该schema为json提作为请求值.Gitee #I1VLHH,如下图：

7、调试栏新增AfterScript特性,开发者可根据Knife4j定义的全局变量编写自定义JavaScript脚本,增强接口交互体验Gitee #I1YNU3、Gitee #I1CAAD,关于AfterScript特性可参考文档

主要应用场景：

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

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

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

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

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

代码如下：

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。如下图：

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

12、增强模式的改进,主要有两个变化,更加详细的使用规则，开发者请参考文档：

  • 提供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

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

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

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

18、请求示例和响应示例中的长整形精度丢失的问题GitHub #269

19、针对当前接口存在Authorze认证情况下，没有点击该功能时参数不会默认在接口调试中的Bug以及query类型参数始终出现在请求头参数栏的情况Gitee #I1VC4I

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

21、增强注解@ApiOperationSupport与@DynamicResponseParameters同时使用时,动态响应字段丢失的问题Gitee #I22K0R

22、离线文档下载失败的问题，变量引用错误导致Gitee #I1W5UB

OpenAPI3

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

Maven引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--如果想使用springfox3.0及OpenAPI3请用3.x版本-->
    <version>3.0</version>
</dependency>

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

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

相关ISSUES:

2.0.5

3 years ago

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.

2.0.4

3 years ago

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

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

2、在当前文档页添加复制接口功能，便于开发人员快速复制接口地址github #238

3、修复Authorize修改或注销的问题gitee #I1IJK3

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

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

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，示例代码如下：

@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

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

"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

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

2.0.3

3 years ago

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

特性 & 优化

knife4j

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

knife4j-spring-ui

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Knife4j-Admin

knife4j-admin是一个基于Spring Cloud Gateway网关,通过网关的特性,结合knife4j对Swagger的文档进行动态聚合的管理平台

平台特点：

  • 跨语言、跨平台
  • 任意聚合Swagger文档,动态发布,调试
  • 文档个性化配置、权限等
  • 彻底告别聚合网关文档等由于软件版本等造成的技术集成问题
  • 独立部署

如果你有以上的需求的话,可以考虑使用一下knife4j-admin这个产品，产品文档点这里

2.0.2

4 years ago

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

特性 & 优化

knife4j

1、新增knife4j-dependencies模块,管理knife4j的相关Maven引用,可以以Maven的BOM方式引入Knife4j

2、官网文档同步更新.

3、解决swagger-annotations导致的版本冲突gitee #I17G31、GitHub #191

knife4j-spring-ui

1、修复切换tab之后 再次发送请求不带参数且不显示响应数据的问题，调试异常等问题PR 13 @gitee、gitee #I17FFX、GitHub #196、GitHub #187

2、优化调试框全部选中的问题,在取消全选时,只有在输入参数改变时才会选中该参数,取消原来默认选中全部参数gitee #I19V6D

3、针对Form表单类型的请求构造curl命令行时在未输入值的情况下为null的情况,修改为空字符串gitee #I18IBZ

4、优化全局参数设置功能,针对参数数据太长不换行问题，以及参数需要修改时需要重新删除的交互体验，开发者在新增参数后可以方便的更改参数数据值以及参数的类型gitee #I17OV1、gitee #I19GJK、gitee #I1A9V1、gitee #I18HMJ、GitHub #176

5、请求参数在未给定example默认值的情况下,文本输入框的placeHolder属性显示该字段的文字说明gitee #I17RKI

6、修复增强属性忽略参数不生效的问题gitee #PR-16、gitee #I136KU、gitee #I187VN、gitee #I16A71

7、调试参数框增加对后端枚举的支持,改输入框为下拉选择框gitee #I18MHO

8、service-worker.js报404问题，构建打包时添加此文件gitee #I17D0Y、GitHub #185

9、get请求参数出现特殊字符未编码处理导致出现400错误gitee #I19C8Y

10、后端新增接口或者接口编辑后,在ui界面显示更新标志,在菜单上会出现一个蓝色的徽标gitee #I1AQFW，如下图:

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

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

13、针对Authorize菜单栏的参数,保存参数是全局保存,其它逻辑分组的接口再调试时,不需要再保存一次新值gitee #I16Z10

14、修复部分情况响应字段在ace-editor编辑器右边栏不显示字段说明的情况gitee #I17F5Y

15、搜索框完善对接口请求Api地址栏的模糊搜索匹配gitee #I19EN0、gitee #I1B0Q9

16、调试响应数据行太长,无法换行的问题gitee #I17F1J

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

如果你后端是Java+Spring的技术栈，在使用springfox的同时，想换一个Swagger的Ui皮肤，通过在pom.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的,如下：

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

如果是微服务的情况下,微服务其实不需要引用Ui的jar包，只需要在网关引用Ui的jar包依赖,所以在微服务情况下,使用增强属性只需要引用微服务版本的starter依赖,如下：

<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.1

4 years ago

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

文档：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、解决x-www-form-urlencoded类型的表单请求，参数勾选复选框无法取消的情况gitee #I16S14

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

3、实现全局搜索功能gitee #I16ZW4

4、@Deprecated 标记的接口置为过时gitee #I1736T

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

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

7、实现图片预览功能gitee #I173AN

如果你后端是Java+Spring的技术栈，在使用springfox的同时，想换一个Swagger的Ui皮肤，通过在pom.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的,如下：

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

如果是微服务的情况下,微服务其实不需要引用Ui的jar包，只需要在网关引用Ui的jar包依赖,所以在微服务情况下,使用增强属性只需要引用微服务版本的starter依赖,如下：

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