758 Star 6.5K Fork 1.4K

GVP萧明 / knife4j

2024-01-08 10:46
118100 xiaoym 1578918321 萧明

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

本次迭代

4.5.0版本主要更新如下:

1、前端i18n增加对日语的支持,感谢一堃通行 ,Gitee#PR98

2、修复EnvironmentPostProcessor中存在defaultProperties与业务冲突的问题,感谢leilei,Gitee#PR100

3、修复addOrderExtension方法报错空指针问题,感谢doublek24Gitee#PR99

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

5、OpenAPI3规范中未配置springdoc.group-configs.packages-to-scan属性导致的空指针异常Gitee#I8O7E8

6、实体参数,@Schema的description属性显示的异常问题Gitee#I8EVO3Github#690

7、OpenAPI3规范请求类型针对format属性的展示问题Gitee#I8KRWV

8、自定义文档】多服务聚合后如果服务名包含"-"会导致自定义文档页刷新报错Gitee#I8EKAQ

9、移除文档favicon.ico的引用Github#716

最后提交信息为: docs:更新日志
2023-12-10 18:45
118100 xiaoym 1578918321 萧明

1、针对eureka注册中心将服务名称转大写的情况,knife4j-gateway聚合失败的处理,感谢DongLiusuoPR贡献Gitee#93

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

3、网关聚合场景下,springdoc子服务默认default地址404的问题优化Gitee#I7RAP7

4、knife4j-gateway组件在boot3中basic密码不兼容的情况#pr652

5、SpringBoot3环境下的javax.filter的兼容性问题修复Github#667

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

7、修复SecurityDocketUtils对SecurityContext的Reference绑定错误的问题Gitee#I88IYH

8、导出的离线Html文档引用CDN源替换为国内的源Gitee#I8C85P

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

10、spring-EnvironmentPostProcessor中存在defaultProperties与业务冲突的问题,主要是springfox兼容高版本boot的问题修复Github#686

11、针对Authorization不生效的问题请参考博客:OpenAPI3规范中添加Authorization鉴权请求Header不生效?

最后提交信息为: docs:文档更新
2023-08-07 08:54
118100 xiaoym 1578918321 萧明

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

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

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

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

Maven坐标

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

更新日志

优化knife4j-gateway组件

1、在gateway网关聚合服务中,排除其他服务支持正则表达式

knife4j:
  gateway:
    enabled: true
    strategy: discover
    discover:
      version: swagger2
      enabled: true
      excluded-services:
        # 排除order开头的配置
        - order.*

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

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

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

5、在手动聚合模式(manual)下同时支持swagger2openapi3规范的聚合

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

2、数据存在枚举值时,SwaggerModel无法正常展开Gitee#PR90

3、解决组件冲突的问题GitHub#630

4、增加title属性的支持Gitee#I7KUYP

感谢

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

最后

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

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

最后提交信息为: docs:更新文档
2023-08-01 08:53
118100 xiaoym 1578918321 萧明

大家好,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,开发者可不用在独立配置,感谢当幸福碰错了头PR

2、支持除default默认分组外的多分组类型,感谢谢进伟PR

3、针对在Dubbo场景下会出现聚合各个Service的场景,该版本提供自动排除服务的扩展SPI接口,开发者可集成自动扩展实现规则进行聚合服务的排除,参考Gitee#I6YLMB

@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#giteeGitHub#609、[Gitee#I6KYUJ][#I6KYUJ:nginx映射后导致请求的url缺少二级路径]、GitHub#603GitHub#586

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

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#I6T78EGitHub#568

2、OAS2新增allof特性的支持Github#PR589

3、针对jakarta环境中Basic的属性提示已经match优化GitHub#578

⛺ 增强部分

1、openapi3规范中增加对@ApiSupport增强注解的支持Gitee#I79WIJ

2、Post发送请求query的方式修改Gitee#I7DNRP

3、优化基础jar包的引用关系,lombok、slf4j等jar包级别改为providedGitHub#591

🤝 感谢

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

最后提交信息为: docs:更新文档
2023-03-24 08:43
118100 xiaoym 1578918321 萧明

大家好,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

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

4、增强属性自定义文档加载分组的bug处理GitHub#PR525

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

6、解决不添加 springdoc-openapi-ui 依赖异常的问题Gitee#I66YJA**

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

8、针对OAS3规范中扩展属性包括排序、作者等不生效的问题Gitee#I6FB9I

9、部分字段翻译问题GitHub#540

10、使用增强属性开启production时出现的NPE异常GitHub#527

11、针对OpenAPI3规范的tag名称兼容性问题Gitee#I6JATP

12、实体类接收url参数时文档不显示参数说明的问题Gitee#I6H8CD

13、修复OAS3规范上传组件的识别问题Gitee#I6HAW0GitHub#538

14、SpringWebflux框架的集成组件starter封装GitHub#521

15、针对Basic验证的特性增加include属性,允许开发者自定义配置GitHub#530

16、全局搜索框支持tag名称的模糊搜索Gitee#I6NWV6

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

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

1、引入starter依赖,maven坐标如下:

<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

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

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

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

示例程序

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

示例如下:

社区

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

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

输入图片说明

仓库坐标

最后提交信息为: perf:Knife4jInsight版本升级
2022-12-20 16:19
118100 xiaoym 1578918321 萧明

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发展的可持续性,整个架构重新梳理,后续可以根据不同的需求,提供不同的服务
输入图片说明

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

统一版本

在此次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坐标如下:

<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坐标如下:

<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坐标如下:

<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之前的增强配置属性(老的):

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

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

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的数据源可以轻松放到配置中心中,实现文档的聚合

架构图如下:
输入图片说明

文档

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

输入图片说明

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

示例程序

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

示例如下:

社区

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

关注公众号"Knife4j",点击菜单获取加群二维码
输入图片说明

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

#I5LIQZ:Knife4j 4.0计划

最后提交信息为: build:v4.0.0 RELEASE
2021-06-28 19:15
118100 xiaoym 1578918321 萧明

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

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://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#I34NOSGitee #I3BRWT:3.0 版本文件上传不显示上传选择文本域

3、OpenAPI3.0规范中Swagger models 中的枚举显示PR #43:参数对象里属性加了required=true,文档上是否必须列依然是falseGitee #I3DP8P:枚举类型在Swagger Models 上未 能正常展示

4、针对OpenAPI3.0规范权限拦截问题增加接口地址Gitee #I2810R:3.0.2 配置生产环境屏蔽后,依然可以访问部分接口Gitee #I3HSK4:生产环境屏蔽 bug

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

6、针对OpenAPI3规范中图片预览的问题优化Gitee #I3IUUQ:springfox 3.0.0、knife4j 3.0.2生成的api文档,调试时不能正确预览gif格式的验证码

聚合组件aggregation

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

2、aggregation聚合组件增加order属性,方便开发者排序设置聚合OpenAPI文档的顺序Gitee #I27ST2:使用knife4j-aggregation 聚合文档服务 支持服务名称(左上角下拉框)排序

3、aggregation聚合组件Nacos聚合微服务文档支持Nacos用户名及密码访问OpenAPI接口Gitee #I28IF9:knife4j-aggregation-spring-boot-starter的Nacos模式不支持Nacos用户名和密码。

4、聚合组件日志打印信息优化,增加isDebugEnabled逻辑判断,日志级别全部由info改为debug级别Gitee #I39QPL:关于knife4j-aggregation-spring-boot-starter日志打印级别

5、聚合组件响应Model不显示的问题Gitee #I3EMZE:Knife4jAggregation与swagger3.0 返回参数不显示

6、聚合组件没有正确响应接口的状态码信息PR #44:1.7.7版本@ApiModelProperty的required=true时ui页面显示还是false

7、基于Eureka/Nacos注册中心的聚合组件,增加心跳检测机制(30s/per),自动剔除已经下线的服务,保证聚合文档的正常访问Gitee #I2CKQT:nife4jAggregation,Nacos模式,配置10个服务,有部分服务没启动,集合服务页面打开一片空白Gitee #I2CDCK:Knife4jAggregation,Nacos模式,服务IP变更后,访问出错Gitee #I2KUUY:Knife4J Aggregation 2.0.8 集成Nacos的问题

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

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

常规

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

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

3、修复离线导出Markdown文档自定义文档为undefined的问题Gitee#I2EDI8Gitee #I2WCQG:下载离线文档时,自定义文档显示为附录undef

4、日志的打印优化Gitee #I39QPL:关于knife4j-aggregation-spring-boot-starter日志打印级别

5、微服务聚合时basePath不追加的问题Gitee #I3B5BK:网关聚合 无法添加 basePath Gitee #I3EEJ3:部分接口显示的链接 丢失 basePath

6、针对List类型示例值多出换行符的问题Gitee #I2D6D4:knife4j 注解List示例值时,请求示例中多出\n

7、解决Form类型上传参数时传递Null的问题Gitee #I3AHDQ:knife4j 参数不传值,后端接收参数值为“null”字符串

8、针对个性化配置的保存问题修改逻辑,开发者通过界面保存个性化配置后丢失的问题Gitee #I27CN8:2.0.8 个性化设置配置失效Gitee #I2CBZQ:2.0.8 个性化设置刷新页面后丢失Gitee #I2978Y: 开启RequestMapping接口过滤,默认只显示POST 勾选后无效Gitee #I3IEXT:3.02 增强模式配置不生效,UI增强功能都没有了 Gitee #I3Q0MO:在网关中,设置host后刷新文档会失效Gitee #I3QSAN:缓存失效

9、针对接口分组中不存在API接口时出现链接点击空白的问题处理,如果分组下没有API接口,默认点击显示主页Gitee #I2CVTF:如果一个controller下没有任何方法, knife4j上生成这个controller菜单点击后直接跳到空白页面

10、OpenAPI规范中tags缺失时导致接口不显示的问题优化,增加default默认分组Gitee #I27M98:knife4j 3.0.2 json 缺乏tags值时,接口统计有,但接口展示出不来

11、针对服务端使用@RequestMapping注解通过method限定方法类型时,Ui增强功能过滤不生效的问题Gitee #I28RJ5:@RequestMapping中如果有method={xxx,xxx},文档的RequestMapping接口过滤就会失效

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

13、优化响应html/xml/text等内容时展现方式Gitee #I2A0QA:返回结果为一个html时,会报错Network Error

14、分组下拉框搜索失效的问题Gitee #I3BAOK:knife4j-aggregation-spring-boot-starter Bug反馈

15、优化OpenAPI版本判断的逻辑,根据响应OpenAPI规范JSON再判断获取当前的规范版本,防止出现空异常或Model不显示等问题Gitee #I37X0Q:app.0f2f48b5.js:1 TypeError: Cannot read property 'indexOf' of undefinedGitee #I3EMZE:Knife4jAggregation与swagger3.0 返回参数不显示

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

17、调试发送时增强loading效果体验Gitee #I3BG5V:knife4j 2.0.8,接口调用时loading效果不太明显,因为这个点被公司回退到了swagger2版本...

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

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

20、解决afterScript特性不能添加多个参数的问题Gitee #I3OJUW:版本2.0.8 3.0.2 ,AfterScript 不能设置多个参数

21、优化响应内容判断base64导致效率低下的问题Gitee #I2VRD5:[3.0.2] 返回结果定义三层,内存飙升并且页面卡死

22、针对增强注解@ApiOperationSupport提供的ignoreParameters属性提供正则模式的忽略策略支持Gitee #I21ZKC:ApiOperationSupport的ignoreParameters参数,是否可以支持正则表达式

2020-11-23 09:49
118100 xiaoym 1578918321 萧明

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

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

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

3、OpenAPI开放接口可以通过增强配置是否显示Gitee #I25273:建议增加Open的tab页屏蔽功能

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:2.0.7路径bugGitee #I23N6L:整合gateway的时候 2.0.7版本及3.0.1版本少了一层basePathGitee #I25ZTC:升级到2.0.7版本后,使用spring cloud gateway聚合接口,出现没有basePath情况GitHub #286:如何更改访问地址

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

9、去除文档右上角?号的文档显示Gitee #I24ZYL:右上角帮助文档问题

10、增强配置增加开启动态请求参数配置的配置Gitee #I24EBO:版本2.0.7 yml配置中没有开启动态请求参数的配置么?

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

11、如果当前服务只有一个分组的情况下,开发者可以通过配置enableGroup项来控制界面的分组显示Gitee #I25MQG:建议加上分组标签屏蔽配置,配置如下:

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

最终效果图如下:

12、基础类型的请求参数与响应参数示例显示优化Gitee #I24YKT:【版本2.0.7】 基本类型(String、Int、Boolean等)不显示响应参数和响应示例

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

14、解决V3版本中starter存在冲突的问题Gitee #I2420J:knife4j 3.0.1--spring boot 2.3.2 Exception: Failed to read configuration metadata

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

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

17、OpenAPI3结构中支持表单类型中scheme解析显示为jsonGitee #I24PCZ:OpenApi3.0 中的content语法何时能够支持呢

18、针对Authorize标志的接口,添加锁的icon在接口中进行体现Gitee #I23W0S:2.0.7版中,SecurityContext的forPaths无效

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

20、针对禁用文档管理菜单项后,同步禁用右上角个性化菜单的显示。Gitee #I262VN:2.07后导航栏个性化配置菜单可以屏蔽了,那么页面右上角个性化配置也应该取消

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

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

22、菜单收缩时显示存在异常的问题Gitee #I2646F:2.0.7及3.0.1版本左侧菜单收缩后侧边栏显示不全

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文档的聚合

四种不同的方式:

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

2020-11-02 10:59
118100 xiaoym 1578918321 萧明

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

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://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:knife4j-spring-boot-starter2.0.6版本文档中生成的url错误,导致接口无法调试Gitee #I23G5V:2.0.6 context-path 多映射了一次的问题

4、导出出md离线文档请求参数部分字段的设置和文档中同步Gitee #I22UFA:下载markdown后文字渲染错误

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:无法兼容spring requestmapping param参数

10、3.0版本不支持Authorize的问题Gitee #I22WVM:knife4j升级到3.0未显示authorize输入栏

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>
最后提交信息为: !313.0.1 RELEASED
2020-10-26 11:50
118100 xiaoym 1578918321 萧明

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

关键词OpenAPI3Auth2.0AfterScriptSpringfox3.0增强改善

文档https://doc.xiaominfo.com

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

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

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://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:knife4j-spring-boot-starter2.0.5版本重现required=true,文档上依然是falseGitee #I1WCMF:2.0.5版本有是否必填显示的bugGitee #I1VDSH:[2.0.5]post对象下面 @ApiModelProperty注解require解析错误GitHub #277:spring cloud gateway整合knife4j后,basePath出现逗号

3、针对服务端指定consumes的情况优化,如果服务端不指定,Ui会默认根据参数类型进行适配Gitee #I1VE25:2.0.3,2.0.4,2.0.5都存在请求数据类型不能自行修改的问题

4、解决在创建Docket对象时赋予Host属性后,文档界面显示接口地址异常的问题Gitee #I1XYG9: Docket对象添加host https://www.xxx.com,接口文档路径显示错误,自动将域名进行加入路径名

5、微服务网关聚合文档时,自定义分组名称导致增强失败的问题Gitee #I1Y79W:/v2/api-docs-ext 接口拼接的group有误

6、针对query类型的参数,如果该参数是schema类型,解析该schema为json提作为请求值.Gitee #I1VLHH:[2.0.5]对象参数在query中提交,在调试中没有把json自动回显,如下图:

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:默认参数header里的allowableValues不能下拉选

代码如下:

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:postman生态的融合。如下图:

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注解或者@ApiSortController类上进行使用,优先级@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:1.8.4版本get查询列表数据界面不显示json内容

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:当返回值只有一行时header的高度太窄

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

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

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

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

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:

最后提交信息为: !273.0 merge
2020-09-15 09:53
118100 xiaoym 1578918321 萧明

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:API 数量50个 操作和切换选项卡 异常卡顿、Gitee #I1LWNM:更新到 2.0.4版本后,接口无法打开、Gitee #I1J52C:knife4j(2.0.2)swagger(2.9.2),离线文档无法使用html下载、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:发送请求参数不写的话为null、Gtiee #I1QXJ1:请问参数支持空字符串传递吗

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

7、在左侧菜单接口中新增接口类型,并且在分组中显示当前分组下包含的接口数量Gitee #I1PE0H:侧边栏可否同之前一样,直接显示请求类型,如下图:

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

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

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

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

12、返回大数据量造成页面卡死的问题优化Gitee #I1QIJK:调用接口后,返回1万多行数据的json,造成页面卡死

13、优化默认的标题显示,开发者未设置分组服务标题时文档标题默认显示Knife4j 接口文档Gitee #I1P4OQ:页面title如果有配置,初始化时默认“Knife4j接口文档”,然后再变成设置的title值,体验不好,是否去掉?

14、枚举类型针对Array数组类型支持多选Gitee #I1NOTE:enum array 不可多选、GitHub #267:Swagger字段属性说明不显示问题(已阅读https://doc.xiaominfo.com/faq/swagger-des-not-found.html)

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

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

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

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

19、支持UiConfiguration中方法调试的配置,如并未配置任何支持的方法,在ui界面中不会出现调试栏TabGitHub #241:接口排序问题,代码如下:

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

20、接口文档中针对请求参数存在示例值的情况下,在接口的参数说明中予以显示GitHub #109:1.8.3版本@RequestParam映射无效

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

最后提交信息为: !252.0.5 RELEASED
2020-06-28 12:40
118100 xiaoym 1578918321 萧明

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

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://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:Authorize 修改或注销的问题(2.0.3)

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:2.x版本图片预览失效

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:使用knife4j生成的markdown文件 ,其中Response参数缺失type,还有schema为false。

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

最后提交信息为: 2.0.4 RELEASED
2020-05-24 16:10
118100 xiaoym 1578918321 萧明

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

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://github.com/xiaoymin/swagger-bootstrap-ui

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

特性 & 优化

knife4j

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

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:String类型默认传参nullgithub #213:接口展示优化建议

4、针对开发者在调试时更改接口地址,在接口地址中添加参数的情况,出现发送请求失败的buggitee #I1C5OQ: 加了额外的参数就识别不了最外层的参数

5、解决集成文档时各种basePath问题导致Ui的logo不显示的问题,通过Base64将logo图片转换处理,img标签直接显示base64字符串gitee #1CQ1F:项目 带了应用名 接口调用失败

6、左侧菜单栏在收缩状态下显示版本控制的标识导致菜单异常的问题,在收缩状态下禁用该项gitee #I1CCXT:左侧菜单有个小buggitee #I1DBDF:未读接口,收起导航显示错误

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

8、服务端在没有Write任何数据的情况下,针对非200状态码不显示状态的异常问题gitee #I1BKRH:调试界面响应码404和201不显示

9、针对raw类型的请求接口类型,全局参数中只能是header参数的问题,支持query类型的全局参数gitee #I1C86F:接口参数为json类型,token只能在head中携带,url无法携带token

10、增加对Xml请求的适配支持,服务端consumes属性设为application/xml接口gitee #I1BCKB:不支持application/xml请求,xml入参和xml出参,界面显示的还是json格式

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

12、剔除webjar文件中的favicon.ico文件,以避免和主项目产生冲突gitee #I1ELHN:knife4j-spring-ui-2.0.2.jar!\META-INF\resources\favicon.ico 请问这个图标怎么覆盖?github #215:功能建议,自定义左侧菜单,添加自定文档

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

14、优化在editor编辑器中的属性字段显示效果gitee #I1G3G9:请求示例和响应示例以及响应内容的"显示说明"的问题

15、导出的Html、Markdown离线文件添加作者属性gitee #I1EXXO:导出得html文档,没有作者这一栏

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

17、优化请求数据类型的显示问题,Ui自动根据参数的类型识别出当前接口的请求类型并进行展示,解决springfox等框架始终解析为json请求的buggitee #I1EMJ9:请求数据类型[ "application/json" ]怎么改?gitee #I1903T:全局设置的consumes不显示

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

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

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

21、添加对springdoc框架的集成支持

如果你后端是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.3 RELEASED
2020-03-08 19:55
118100 xiaoym 1578918321 萧明

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

Giteehttps://gitee.com/xiaoym/knife4j

GitHubhttps://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:knife4j-micro-spring-boot-starter自身存在冲突..GitHub #191:调试返回结果缓存问题

knife4j-spring-ui

1、修复切换tab之后 再次发送请求不带参数且不显示响应数据的问题,调试异常等问题PR 13 @Giteegitee #I17FFX:api 切换请求、响应BUG(2.0.1)GitHub #196:开启生产环境,屏蔽Swagger所有资源接口 建议GitHub #187:点击离线文档导致页面奔溃

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

3、针对Form表单类型的请求构造curl命令行时在未输入值的情况下为null的情况,修改为空字符串gitee #I18IBZ:2.0.1 不填参数应该传递 "" 或者不传递该参数,而非

4、优化全局参数设置功能,针对参数数据太长不换行问题,以及参数需要修改时需要重新删除的交互体验,开发者在新增参数后可以方便的更改参数数据值以及参数的类型gitee #I17OV1:全局参数不支持修改吗,accessToken过期了 每次要删掉重新创建gitee #I19GJK:全局参数的样式问题gitee #I1A9V1:全局参数设置.字段太长.删除按钮就不见了.但是f12看得到gitee #I18HMJ:强烈建议支持全局参数可以修改,强烈建议全局参数设置后,header中相同的参数不要显示两个GitHub #176:schema下的properties里的ref不能被识别

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

6、修复增强属性忽略参数不生效的问题gitee #PR-16gitee #I136KU:请求参数对象忽略指定参数,在请求示例中部分未忽略gitee #I187VN:忽略参数 JsonObject不生效gitee #I16A71:@ApiOperationSupport 无效

7、调试参数框增加对后端枚举的支持,改输入框为下拉选择框gitee #I18MHO:2.0.1 版本可选参数没有旧版本的那种下拉框

8、service-worker.js报404问题,构建打包时添加此文件gitee #I17D0Y:service-worker.js报错GitHub #185:可否将这个ui的依赖包,放到一个空的springboot项目中,只负责ui显示

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

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

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

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

13、针对Authorize菜单栏的参数,保存参数是全局保存,其它逻辑分组的接口再调试时,不需要再保存一次新值gitee #I16Z10:2.0.0版本,Authorize 设置参数无法统一设置。

14、修复部分情况响应字段在ace-editor编辑器右边栏不显示字段说明的情况gitee #I17F5Y:Knife4j版本字段属性说名缺失问题

15、搜索框完善对接口请求Api地址栏的模糊搜索匹配gitee #I19EN0:新版ui不支持uri索,老版本是支持的gitee #I1B0Q9:Knife4j 2.0.1版本为什么了没有了API地址显示和api地址搜索功能呢?

16、调试响应数据行太长,无法换行的问题gitee #I17F1J: knife4版本相应内容过长不换行

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.2 RELEASED
2019-12-23 10:08
118100 xiaoym 1578918321 萧明

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:2.0.0版本,全局搜索按钮消失

4、@deprecated 标记的接口置为过时gitee #I1736T:2.0.0 版本, @Deprecated 标记的接口,没有显示 删除线 了

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

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

7、实现图片预览功能gitee #I173AN:2.0.0 版本, 图片无法预览?

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

最后提交信息为: 2.0.1 RELEASED
2019-12-16 09:39
118100 xiaoym 1578918321 萧明

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>

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

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

特点

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

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-bootstrap-ui的最后一个版本

这是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:swagger ui框架的model显示功能建议 @adminchen

3、优化请求头Header是中文的情况,如果包含中文则进行encodeURI函数处理,否则不做任何处理#140:图片预览不能显示 @adminchen

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 @adminchen

Maven坐标

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.6</version>
</dependency>
2019-07-31 21:13
118100 xiaoym 1578918321 萧明

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:响应内容无高亮 版本1.94 @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:是否可以添加一个变量之类的,自定义一下调试功能的显示? @adminchen

8、修复非200状态码响应内容不格式化高亮的问题#130:接口入参: list 点击增加 按钮,无效 @adminchen

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

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

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
2019-06-10 17:14
118100 xiaoym 1578918321 萧明

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:右侧关闭tab菜单优化 @Gitee

6、增加调试接口响应类型为Xml、Html、Text的支持#IWP49:返回xml格式报错 @Gitee

7、优化调试后header、raw、curl等选项卡高度太低的问题#IWLSU:当返回值只有一行时header的高度太窄 @Gitee

8、主页简介description字段支持markdown格式#IVVRX:description不支持MarkDown语法 @Gitee

9、针对枚举类型的集合类型(List),在字段描述中显示枚举可用列表值#100:v1.8.2的 parameters 如果in参数是formData时, 字段是否填写判断有问题么? @adminchen

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

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

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

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

2019-04-23 16:50
118100 xiaoym 1578918321 萧明

swagger-bootstrap-ui 1.9.3 发布了。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、增加i18n国际化支持(中文、English),可参考文档

2、优化调试框请求参数类型,添加数据类型issue #IVF2L:调试模块的参数类型显示错误 @Gitee

3、接口描述支持Html渲染issue #IVBWM:接口描述是否不支持html渲染 @Gitee

4、允许添加自定义文档(以markdown的形式)issue #IUWN9:功能建议,自定义左侧菜单,添加自定文档 @Gitee,可参考文档

5、优化非200状态码调试栏显示高度过低的情况.

6、分组tag名称很长时超出bug,增加菜单title鼠标悬浮显示分组tag名称issue #IVE0S:api文件名称过长会换行 @Gitee

7、初始化请求异常处理,弹出友好提示信息.

8、接口任何信息变更和新增接口一样,添加new的icon图表样式,代表当前接口信息已产生变化.

9、Swagger Models中的属性类显示readOnly|example属性issue #77:1.8.1文件上传的bug @adminchen

Bug修复

1、解决多个api文档切换时,Authorize的参数没有变更的bugissue #IV3OZ:多个api文档切换时,Authorize的参数没有变更 @Gitee

2、解决Basic认证出现的空指针异常以及账户密码为空的时候,页面崩溃的情况issue #78:全局参数与接口参数相同时会出现两个 相同参数 并且某一个为空 如图 @adminchen

最后提交信息为: 1.9.3.RELEASED
Java
1
https://gitee.com/xiaoym/knife4j.git
git@gitee.com:xiaoym/knife4j.git
xiaoym
knife4j
knife4j

搜索帮助

14c37bed 8189591 565d56ea 8189591