knife4j是为Java MVC框架生成Api文档的增强解决方案 knife4j

Apache
Java JavaScript
跨平台
2017-04-19
八一菜刀

你与数据分析专家,只差一个强大的数据库引擎!>>>

GitHub    Gitee    项目文档    项目demo    在线体验

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui,为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

更名后主要专注的方面

  • 前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
  • 提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分

效果:http://swagger-bootstrap-ui.xiaominfo.com/doc.html

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

交流: 

 

文档:https://doc.xiaominfo.com/

源码分析:https://www.xiaominfo.com/2019/05/20/springfox-0/

项目模块

目前主要的模块包括:

模块名称 说明
knife4j 为Java MVC框架集成Swagger的增强解决方案
knife4j-admin 云端Swagger接口文档注册管理中心,集成gateway网关对任意微服务文档进行组合集成
knife4j-extension chrome浏览器的增强swagger接口文档ui,快速渲染swagger资源
knife4j-service 为swagger服务的一系列接口服务程序
knife4j-front knife4j-spring-ui的纯前端静态版本,用于集成非Java语言使用
swagger-bootstrap-ui knife4j的前身,最后发布版本是1.9.6

业务场景

不使用增强功能,纯粹换一个swagger的前端皮肤

不使用增强功能,纯粹换一个swagger的前端皮肤,这种情况是最简单的,你项目结构下无需变更

可以直接引用swagger-bootstrap-ui的最后一个版本1.9.6或者使用knife4j-spring-ui

老版本引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

新版本引用

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>${lastVersion}</version>
</dependency>

Spring Boot项目单体架构使用增强功能

在Spring Boot单体架构下,knife4j提供了starter供开发者快速使用

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

该包会引用所有的knife4j提供的资源,包括前端Ui的jar包

Spring Cloud微服务架构

在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter

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

在网关聚合文档服务下,可以再把前端的ui资源引入

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

另外说明

不管是knife4j还是swagger-bootstrap-ui

对外提供的地址依然是doc.html

访问:http://ip:port/doc.html

即可查看文档

这是永远不会改变的

提ISSUES必看

虽然建立了QQ交流群,但是很多没用加群的朋友会通过ISSUES来反馈问题,提ISSUES本身是一个很好的技术习惯,这有助于帮助我能很好的定位问题所在,但因为我并不是实时关注,所以经常在我处理issues的时候,看到很多朋友提的问题却也无从着手,写下一些建议,希望提ISSUES的朋友能在提的时候都有涉及到:

1、swagger-bootstrap-ui和springfox-swagger的版本号,这个尤为重要,很多低版本出现的问题有可能我在新发布的版本中已经解决了,每个版本都有更新日志,可以参考这篇文档:https://doc.xiaominfo.com/changelog/

2、提ISSUES时贴图、贴代码,代码不用贴逻辑,只需要贴接口层即可,还有相关的实体类(如果有涉及的话),这些信息有助于我快速定位问题,省去了来回沟通的成本,提高大家的效率

3、在QQ交流群沟通的朋友我也希望能通过提ISSUE来记录下我们沟通的过程,我并非实时处理此问题,这让我集中再处理issues的时候有助于拉回我们彼此沟通时的场景,最终在新版本解决问题

4、swagger-bootstrap-ui使用的是传统的JS技术,jQuery+Dom操作,打包后的源码也并没有压缩处理,代码注释部分我也有说明,应该是能理解的,如果我没有及时处理碰到的问题,欢迎大家提交pr,毕竟众人拾柴火焰高嘛

项目Demo示例

Demo示例见另外项目地址:https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

模块 说明
knife4j-spring-boot-demo 在Spring Boot架构下集成knife4j的项目示例
knife4j-spring-boot-single-demo 在Spring Boot单体架构下集成knife4j的项目示例
knife4j-spring-cloud-gateway 在Spring Cloud微服务架构下通过gateway网集成knife4j的示例
swagger-bootstrap-ui-demo-mvc 在Spring MVC模式下集成swagger-bootstrap-ui
swagger-bootstrap-ui-demo 在Spring Boot单体架构下集成swagger-bootstrap-ui
swagger-bootstrap-ui-gateway 在Spring Cloud微服务架构下通过gateway网关集成swagger-bootstrap-ui
swagger-bootstrap-ui-zuul 在Spring Cloud微服务架构下通过zuul网关集成swagger-bootstrap-ui

界面效果

的码云指数为
超过 的项目
加载中
此软件有 22 条评论,请先登录后再查看。

Knife4j 2.0.3 正式发布,支持 springdoc 和 i18n

Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能的工具 文档:https://doc.xiaominfo.com 效果(旧版):http://swagger-bootstrap-ui.xiaominfo.com/doc.html 效果(2.X版):h...

05/25 09:36

knife4j-admin v1.0发布,任意聚合 Swagger 文档

knife4j-admin是一个基于Spring Cloud Gateway网关,通过网关的特性,结合knife4j对Swagger的文档进行动态聚合的管理平台 平台特点: 跨语言、跨平台 任意聚合Swagger文档,动态发布,调试 文档个...

05/20 11:22

Knife4j 2.0.2 正式发布,Swagger 接口文档赋能工具

Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档赋能的工具 文档:https://doc.xiaominfo.com 效果(旧版):http://swagger-bootstrap-ui.xiaominfo.com/doc.html 效果(2.X版):h...

03/09 08:50

Knife4j 2.0.1 发布,细节处理!

Knife4j前身是swagger-bootstrap-ui,是一个为Swagger接口文档服务的工具 文档:http://doc.xiaominfo.com 效果(旧版):http://swagger-bootstrap-ui.xiaominfo.com/doc.html 效果(2.0版):htt...

2019/12/23 09:15

Knife4j 2.0 发布,涅槃重生~!

Knife4j前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前...

2019/12/16 08:55

swagger-bootstrap-ui 1.9.6 发布,解决长整型精度丢失的问题

swagger-bootstrap-ui 1.9.6 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿 文档:http://doc.xiaominfo.com 效果:http://swagger-bootstrap-ui.xiaominfo.c...

2019/08/29 09:29

swagger-bootstrap-ui 1.9.5 发布,支持过滤请求参数

swagger-bootstrap-ui 1.9.5 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿 文档:http://doc.xiaominfo.com 效果:http://swagger-bootstrap-ui.xiaominfo.c...

2019/07/31 21:06

swagger-bootstrap-ui 1.9.4 发布,扩展支持动态字段注释

swagger-bootstrap-ui 1.9.4 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿 文档:http://doc.xiaominfo.com 效果:http://swagger-bootstrap-ui.xiaominfo.c...

2019/06/10 17:17

swagger-bootstrap-ui 应用扩展程序 1.0.0 发布

随着swagger-bootstrap-ui已经历时两年多,发布了26个版本,目前也得到的很多Java开发者的青睐,如果你是使用Swagger来构建你的文档服务,那么,swagger-bootstrap-ui你一定不容错过 正因为如此,...

2019/05/20 09:20

swagger-bootstrap-ui 1.9.3 发布,i18n及自定义文档支持

swagger-bootstrap-ui 1.9.3 发布了。swagger-bootstrap-ui是 Swagger 的增强UI 实现,使文档更友好一点儿 文档:http://doc.xiaominfo.com 效果:http://swagger-bootstrap-ui.xiaominfo.c...

2019/04/23 16:44

没有更多内容

加载失败,请刷新页面

3
回答
knife4j文档测试get接口时发生转换问题

我项目中整合了knife4j,在api文档中对get接口发送请求时,后台报错数据类型转换异常。我接口传递一个实体类,测试的时候没有填值。 有没有遇上过的,...

04/23 16:11
3
回答
swagger设置全局参数(例如token),但是部分接口不需要该全局参数,如何配置?
白菜粉条炖猪蹄儿 的回答 2019/03/22 09:45
最佳答案
@Bean(value = "defaultApi") public Docket defaultApi() { List<Parameter> pars = new ArrayList<Parameter>(); ParameterBuilder tokenPar = new Paramet...
2
回答
Gateway与Swagger2做文档聚合使用knife4j时,报service-worker.js 404
八一菜刀 的回答 03/06 16:45
最佳答案
如果分组出不来,看看swagger-resources接口返回的结构是否正确,正常的结构如下: [ { "name": "分组接口", "url": "/v2/api-docs?group=分组接口", "swaggerVersion": "2.0", "location": "/v2/api...
1
回答
swagger-bootstrap-ui接口请求地址错误

@八一菜刀 你好,想跟你请教个问题: 我的接口地址http://dev.cloud-iot.jinf-iot.com/api/v1/xxx 现在显示效果变...

2019/06/24 14:21
3
回答
swagger-bootstrap-ui 1.7.9 不支持上传文件

@八一菜刀 你好,想跟你请教个问题: 上边两张图是我做的一个上传文件的接口,一个是swagger-ui访问的,一个是swagger-bootstrap-u...

2018/08/20 14:17

没有更多内容

加载失败,请刷新页面

没有更多内容

swagger-ui升级swagger-bootstrap-ui界面好看到起飞

如果项目已经集成了swagger,只需要在pom.xml添加,如果你的项目没有集成swagger,自行百度或看最下方的链接 swagger-bootstrap-ui是Swagger的前端UI实现,目的是替换Swagger默认的UI实现Swa...

2019/09/02 14:59
182
0
springfox-swagger之swagger-bootstrap-ui

swagger-bootstrap-ui是国内的一个swagger开源项目,从发起到现在已经有三年了。 初次体验了一下,觉得还是挺不错的,就如当初使用mybatis-plus那样,因为有了mybatis的基础,所以过渡到myb...

2019/04/28 20:35
53
0
在spring Boot中使用swagger-bootstrap-ui(原文)

1.swagger简介 Swagger是一个API接口管理工具,支持在线测试接口数据,根据配置自动生成API文档,结合spring mvc而提供界面化方法文档的一个开源框架。 1.1Swagger主要的项目 Swagger是一组开...

2019/09/24 23:16
37
0
在spring Boot中使用swagger-bootstrap-ui

转载: https://www.cnblogs.com/fby698/p/11581845.html 把swagger-ui换成swagger-bootstrap-ui (换成swagger-bootstrap-ui更加方便调试和导出文档) GitHub地址: https://github.com/xiaoym...

2019/10/22 10:16
15
0
Swagger-BootStrap-UI生成的接口文档如何加Basic校验

首先我们来看看swagger-bootstrap-ui的效果,如图所示: 看起来是不是比Swagger要大气的多。 回到重点上,为什么要给接口文档加密呢? 只对内开放,不对外开放,防止被第三方非公司人员进行非...

2019/09/07 19:36
13
0
springboot整合Swagger

Swagger简介 1、认识Swagger Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的...

2019/05/13 21:06
13
0
Swagger API文档集中化注册管理

接口文档是前后端开发对接时很重要的一个组件。手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的框架。swagger文档一般是随项目代...

2019/06/28 19:37
39
0
swagger结合shiro如何配置

为了节省开发人员的时间与成本,swagger插件油然而生,省去您写开发文档的时间好好去快乐的玩耍,不说废话,接下来我将使用github上比较受欢迎的swagger-bootstrap-ui插件进行说明讲解,可能...

2019/08/24 15:17
28
0
spring-boot 集成 swagger 问题的解决

spring-boot 集成 swagger 网上有许多关于 spring boot 集成 swagger 的教程。按照教程去做,发现无法打开接口界面。 项目由 spring mvc 迁移过来,是一个无界面纯 API 的项目。迁移之前就支...

2018/01/07 16:47
44
0
java效率开发之使用swagger, 同时推荐使用增强swagger-UI

前言 现代化的研发组织架构中,一个研发团队基本包括了 产品组、后端组、前端组、APP端研发、 测试组、 UI组等,各个细分组织人员各司其职,共同完成产品的全周期工作。如何进行组织架构内的...

2019/03/15 15:05
3.5K
0

没有更多内容

加载失败,请刷新页面

返回顶部
顶部