Swagger友好UI工具之Knife4j

约定不等于承诺〃 2022-09-10 02:14 294阅读 0赞

先上效果图：

![watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaHpvYm95_size_20_color_FFFFFF_t_70_g_se_x_16][]

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

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

## 项目模块 ##

目前主要的模块包括：

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

**官方文档：**[https://doc.xiaominfo.com/knife4j/documentation/][https_doc.xiaominfo.com_knife4j_documentation]

**备份文档地址**：[https://xiaoym.gitee.io/knife4j/][https_xiaoym.gitee.io_knife4j]

**效果(2.0版)：**[http://knife4j.xiaominfo.com/doc.html][http_knife4j.xiaominfo.com_doc.html]

**效果(旧版本)：**[http://swagger-bootstrap-ui.xiaominfo.com/doc.html][http_swagger-bootstrap-ui.xiaominfo.com_doc.html]

**示例:**[https://gitee.com/xiaoym/swagger-bootstrap-ui-demo][https_gitee.com_xiaoym_swagger-bootstrap-ui-demo]

**交流：** [https://doc.xiaominfo.com/knife4j/documentation/help.html][https_doc.xiaominfo.com_knife4j_documentation_help.html]

**源码分析**:[https://www.xiaominfo.com/2019/05/20/springfox-0/][https_www.xiaominfo.com_2019_05_20_springfox-0]

## 业务场景 ##

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

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

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

新版本引用

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

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

访问：[http://ip:port/doc.html][http_ip_port_doc.html]

## 项目Demo示例 ##

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

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

## 界面效果 ##

![接口说明][c25851cdec799ae61dcf840d483b8d37.png]

![接口调试][0c577669ff9df78e08bfe94396b5f47d.png]

![个性化设置][2901501e14acf5b5e7ee4db91be34435.png]

![接口离线文档][a11dcb316f1eb1352d5a0e916cb92dd0.png]

![SwaggerModels][]

[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBAaHpvYm95_size_20_color_FFFFFF_t_70_g_se_x_16]: /images/20220829/117cbaeeb302407b8f368bcc7e28879a.png
[https_doc.xiaominfo.com_knife4j_documentation]: https://doc.xiaominfo.com/knife4j/documentation/
[https_xiaoym.gitee.io_knife4j]: https://xiaoym.gitee.io/knife4j/
[http_knife4j.xiaominfo.com_doc.html]: http://knife4j.xiaominfo.com/doc.html
[http_swagger-bootstrap-ui.xiaominfo.com_doc.html]: http://swagger-bootstrap-ui.xiaominfo.com/doc.html
[https_gitee.com_xiaoym_swagger-bootstrap-ui-demo]: https://gitee.com/xiaoym/swagger-bootstrap-ui-demo
[https_doc.xiaominfo.com_knife4j_documentation_help.html]: https://doc.xiaominfo.com/knife4j/documentation/help.html
[https_www.xiaominfo.com_2019_05_20_springfox-0]: https://www.xiaominfo.com/2019/05/20/springfox-0/
[http_ip_port_doc.html]: http://ip/doc.html
[c25851cdec799ae61dcf840d483b8d37.png]: /images/20220829/4101e39496fc4db8b49e69be073b9235.png
[0c577669ff9df78e08bfe94396b5f47d.png]: /images/20220829/ff728280342f4caeae8da526ae31c8bc.png
[2901501e14acf5b5e7ee4db91be34435.png]: /images/20220829/e771cfc8ff774afabf820001934b7997.png
[a11dcb316f1eb1352d5a0e916cb92dd0.png]: /images/20220829/1e36493cd1b94950a2679f3b78073e94.png
[SwaggerModels]: /images/20220829/a05f9ce90af9439594a98d66542ba11e.png