Knife4j 4.0计划

Knife4j 4.0迭代计划，感兴趣的朋友可以加群参与讨论贡献

关注公众号"Knife4j"，点击菜单“V4.0”获取加群二维码
输入图片说明

几个待处理事项：

一图胜千言
输入图片说明

一、前端部分

1、目前knife4j-ui的版本虽然提供了swagger2、oas3的兼容，但是对于oas3兼容性可能还不太好，需要对照oas3规范捋一遍

2、oas3规范对oauth2的支持，目前还没有做

二、后端部分

1、虽然提供了starter，但是使用起来还是需要创建一些Config配置文件，没有真正的简化使用人员的工作量，需要加强starter的范围，提供基于配置文件即可以快速使用，需要兼容springfox、springdoc-openapi两个版本

2、提供对springdoc-openapi框架的兼容适配，knife4j提供的部分增强功能需要在springdoc-openapi找到突破口，类似于springfox的Plugin扩展机制一样

3、主流API网关的聚合，比如zuul、gateway等组件，目前聚合起来对开发者而言比较吃力或者不同网关版本之间，总是存在各种各样的问题，提供统一的网关聚合starter解决方案

三、生态发展

1、提供独立的中间件，虽然knife4j提供了knife4j-aggregation-desktop组件，但使用起来还是不太方便，需要考虑和目前主流的一些配置中心结合使用，nacos、apoll等等

2、提供Docker官方镜像，一键部署独立中间件，配合k8s，简化独立中间件的使用成本&学习成本

3、各种云原生场景下的适配集成，特别是k8s环境下，目前k8s发展已经成为主流，knife4j在k8s环境下的独立中间件能否出一份力

四、文档

1、官方文档缺乏版本机制，从目前的版本发版，需要将不同的文档-版本进行对应起来

2、各个Spring Boot、Spring Cloud等环境集成knife4j的实战适配

3、FAQ完善

4、Swagger2、OAS3等规范的说明、包括对springfox、springdoc-openapi等框架的说明文档

明细计划拆分进度：

https://xiaoymin.notion.site/Knife4j-4-0-46d7d4424fe44701a960cad30eb72006

支持，期待4.0

更新进度，目前已经发布4.0.0-SNAPSHOT快照版本，可通过配置快照私服地址进行体验

SNAPSHOT快照版本最慢每三天一个周期上传一次，追求尽快发布release版本，大家有问题及时提issue反馈

使用方法

1、项目pom.xml中配置快照仓库，如下：

<repositories>     
     <repository>         
        <id>nexus-maven</id>         
        <name>nexus-maven</name>         
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>     
    </repository>
 </repositories>

2、引入依赖：

以openapi2为例，需要注意的是，从4.0.0版本开始，knife4j提供的starter包artifactId有了变化

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

3、配置yaml

knife4j:   
    enable: true   
    openapi:     
        title: knife4j文档     
        concat: xiaoymin@foxmail.com     
        email: xiaoymin@foxmail.com     
        url: https://gitee.com/xiaoym/knife4j
        version: 1.0     
        group:       
            open:         
                group-name: knife4j文档         
                api-rule: package         
                api-rule-resources:           
                    - com.rest     
                description: knife4j文档   
    setting:     
        language: zh_cn

4、访问

http://ip:port/doc.html

由于时间紧迫，目前文档还没来的及写，可以参考新版本的demo

Spring Boot 2.x + OpenAPI2规范：knife4j-spring-boot27-demo
Spring Boot 2.x +OpenAPI3规范：knife4j-springdoc-openapi-demo
Spring Boot 3+ OpenAPI3规范：knife4j-spring-boot3-demo

20221202 更新最新4.0-SNAPSHOT

关联issue：

Future：

新增模块knife4j-openapi3-jakarta-spring-boot-starter，该模块最低java17

20221203 更新最新4.0-SNAPSHOT

关联issue：

Future：

新增模块knife4j-gateway-spring-boot-starter,参考文档

目前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网关的项目可以引用该组件实现简单的文档聚合,参考文档
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 项目

2022/12/04 更新最新4.0-SNAPSHOT

关联issues：

#I5W145:ApiResponse自定义响应示例，swagger-ui显示，knife4j不显示
https://github.com/xiaoymin/swagger-bootstrap-ui/issues/385
https://github.com/xiaoymin/swagger-bootstrap-ui/issues/157
调试响应curl内容出现空格的问题

Future：

源码新增spotless-maven-plugin插件，统一代码风格

2022/12/05 更新最新4.0-SNAPSHOT

关联issues：

aggregation聚合组件支持当前项目context-path属性
#I64P8J:Knife4jAggregation聚合文档，Cloud模式，服务重启后分组不见了
springdoc-openapi项目针对当前项目context-path的属性支持
https://github.com/xiaoymin/swagger-bootstrap-ui/issues/423
https://github.com/xiaoymin/swagger-bootstrap-ui/issues/422

2022/12/06 更新最新4.0-SNAPSHOT

关联issues：

2022/12/10 更新最新4.0-SNAPSHOT

关联issues：

Future：

knife4j-aggregation-spring-boot-starter组件支持不同环境的调试模式
OpenAPI3规范支持OAuth2的解析适配

2022/12/10 更新最新4.0-SNAPSHOT

关联issues：

Future：

knfie4j-desktop组件基于Spring Boot重写，后期方便兼容生态升级迭代

能不能出个4.0的release版本出来

快了

大概多久，超期待，超想用

肯定不会到2023年的

2022/12/12 更新最新4.0-SNAPSHOT

关联issues：

https://github.com/xiaoymin/swagger-bootstrap-ui/issues/485

Future：

knife4j-openapi3-spring-boot-starter的增强适配
knife4j-openapi3-jakarta-spring-boot-starter的增强适配

另外：
新增Spring Boot3 + springdoc-openapi2(OpenAPI3规范)+Knife4j的demo：knife4j-spring-boot3-demo

该demo中jdk版本必须不低于17

思考：🤔

knife4j与云原生的结合：

knife4j-desktop的数据来源可以不局限于本地配置文件，这个配置文件可以放nacos、Apoll等这类配置中心中间件上，或者直接放k8s上把中间件发挥到极致，将knife4j-desktop组件打包成docker镜像，run anywhere

输入图片说明

基础配置(暂定)：



# knife4j-desktop的数据源类型
knfie4j.source=disk,nacos,apollo,k8s

# disk模式比较简单,只需要配置dir数据目录就可以了，knife4j-desktop自动识别

knfie4j.disk.dir=/knife4j/data



# 如果是远端的配置中心，以nacos为例子,基础配置
knfie4j.source=nacos
knife4j.nacos.server=127.0.0.1:8848
knife4j.nacos.username=nacos
knife4j.nacos.password=nacos
knife4j.nacos.namespace=3
knife4j.nacos.dataId=Knifej-desktop
knife4j.nacos.group=DEFAULT_GROUP


## 下面的这些配置信息，就可以配置在nacos中，指定namespace为"3",并且dataId=Knifej-desktop,gropu=DEFAULT_GROUP的配置中


# 第一个项目数据访问项目名称,字母，数字，字母+数字 http://localhost:port/abc/doc.html
knfie4j.nacos.data[0].name=abc
# abc通过cloud模式
knfie4j.nacos.data[0].cloud.routes[0].name=cloud模式
knfie4j.nacos.data[0].cloud.routes[0].uri=http://localhost:8990
knfie4j.nacos.data[0].cloud.routes[0].location=/v2/api-docs?group=根据包名

knfie4j.nacos.data[0].cloud.routes[1].name=cloud模式1
knfie4j.nacos.data[0].cloud.routes[1].uri=http://localhost:8990
knfie4j.nacos.data[0].cloud.routes[1].location=/v2/api-docs?group=com.focus


# 第二个项目(ddd)数据访问项目名称 http://localhost:port/ddd/doc.html
knfie4j.nacos.data[1].name=ddd
# ddd通过基于nacos的配置进行配置，这种方式代表把离线的OpenAPI规范数据(json|yml)存放到Nacos上，只需要配置相应的dataId、group就可以了
knfie4j.nacos.data[1].disk.routes[0].name=disk模式
knfie4j.nacos.data[1].disk.routes[0].debugUrl=http://192.168.0.11:8080
knfie4j.nacos.data[1].disk.routes[0].dataId=111
knfie4j.nacos.data[1].disk.routes[0].group=DEFAULT_GROUP

knfie4j.nacos.data[1].disk.routes[1].name=disk模式2
knfie4j.nacos.data[1].disk.routes[1].dataId=222
knfie4j.nacos.data[1].disk.routes[1].group=DEFAULT_GROUP

2022.12.15
desktop的架构设计想法：

输入图片说明

2022.12.18日

尝试把knife4j-desktop组件通过GraavlVM编译成单个可执行文件，初步尝试成功，编译后体积大小11MB

Mac M1下：

输入图片说明

执行(本地disk模式)：

./knife4j --knife4j.source=disk --knife4j.disk.dir="/Users/xiaoyumin/tmp/knife4j-desktop"

运行正常:

输入图片说明

Win10环境下编译成exe文件

输入图片说明

2022.12.19

今日knife4j-desktop针对nacos配置中心的支持测试流程完成，通过将desktop打包成docker镜像，在k8s环境中运行，并指定desktop的数据源模式为nacos配置中心，如下图:

输入图片说明

测试，在nacos配置中心配置dataId=test123,group=TEST_GROUP的配置信息，以disk模式为例：

输入图片说明

将OpenAPI的离线JSON文件存放到Nacos上，所以disk模式只需要配置当前nacos的dataId、group两个参数即可
离线的OpenAPI数据如下图:
输入图片说明
通过界面访问：

4.0.0 正式发布了：

https://www.oschina.net/news/222157/knife4j-4-0-released

knife4j-desktop的官方docker镜像：

https://hub.docker.com/repository/docker/xiaoymin/knife4j/general

大佬，遇到个问题，@Schema用在不同类的内部类里面，内部类名称相同，字段不同，这样在页面永远显示的是同一个内部类的字段，怎么才能区分开啊

knife4.0.0版本怎么扫描指定的路径或者注解，像这样呢？.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))

GVP 萧明 / knife4j

内容风险标识

评论 (23)

GVP萧明 / knife4j

内容风险标识