前言：

Swagger现在已经成了最流行的接口文档生成与管理工具，但是你是否在用的时候也在吐槽，它是真的不好看，接口测试的json数据没法格式化，测试地址如果更改了还要去改配置，接口测试时增加token验证是真的麻烦......等等，拿什么拯救你，swagger同学！
针对Swagger的种种缺点，Knife4j就呼之欲出了。

正文

一、先看一下它长什么样子吧

看一下官方的介绍：
??Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的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、非常简洁清爽的UI设计，接口的快速搜索。

2、支持个性化设置，个性化设置包含：

  请求参数缓存

  动态请求参数

  RequestMapping接口过滤

  HOST代理设置

3、全局参数设置，可以很方便的设置Token等权限认证参数。

4、离线API文档下载：

  Markdown（已支持）

  Html（已支持）

  Word（已支持）

  OpenApi（已支持）

5、对 json 格式的数据有更好的支持，可以折叠展开等。

三、Knife4j的集成

1、在Springboot中的集成

（1）在项目 pom.xml 文件中引入 jar 依赖。

<dependency> 
<groupId>com.github.xiaoymin</groupId>
 <artifactId>knife4j-springdoc-ui</artifactId>
 <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
 <version>3.0.2</version> 
</dependency>

完整的 pom.xml 示例

<?xml version="1.0" encoding="UTF-8"?> 
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> 
<modelVersion>4.0.0</modelVersion>
 <parent> 
<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-parent</artifactId> 
<version>2.3.5.RELEASE</version> 
<relativePath/> <!-- lookup parent from repository -->
 </parent> 
<groupId>com.github.xiaoymin</groupId>
 <artifactId>knife4j-spring-boot-fast-demo</artifactId> 
<version>1.0</version>
 <name>knife4j-spring-boot-fast-demo</name> 
<description>Demo project for Spring Boot</description>

 <properties>
 <java.version>1.8</java.version> 
</properties>

 <dependencies> 
<dependency> 
<groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId> 
</dependency> 
<dependency> 
<groupId>com.github.xiaoymin</groupId> 
<artifactId>knife4j-spring-boot-starter</artifactId>
 <version>2.0.7</version> 
</dependency> 

<dependency> 
<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-starter-test</artifactId> 
<scope>test</scope> 
<exclusions> 
<exclusion> 
<groupId>org.junit.vintage</groupId>
 <artifactId>junit-vintage-engine</artifactId>
 </exclusion> 
</exclusions> 
</dependency> 
</dependencies> 

<build> 
<plugins> 
<plugin> 
<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin> 
</plugins> 
</build> 
</project>

（2）创建Swagger配置依赖，代码如下

@Configuration 
@EnableSwagger2WebMvc 
public class Knife4jConfiguration { 

@Bean(value = "defaultApi2")
 public Docket defaultApi2() { 
Docket docket=new Docket(DocumentationType.SWAGGER_2)
 .apiInfo(new ApiInfoBuilder()
 //.title("swagger-bootstrap-ui-demo RESTful APIs") 
.description("# swagger-bootstrap-ui-demo RESTful APIs") 
.termsOfServiceUrl("http://www.xx.com/")
 .contact("xx@qq.com") .version("1.0") 
.build()) 
//分组名称 
.groupName("2.X版本")
 .select() 
//这里指定Controller扫描包路径
 .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller")) 
.paths(PathSelectors.any())
 .build(); 
return docket; 
}
 }

（3）启动项目，查看效果。

浏览器输入：http://ip:端口/doc.html ，即可打开Knife4j页面

四、几个比较重要的功能示例

（1）Token 认证参数的设置。

文档管理》全局参数设置》添加参数

可选择参数是放在 header 还是 query 中。

（2）离线文档

离线文档支持四种格式，Markdown、Html、Word、Open Api

Markdown 文档预览：

Html 文档预览：

（3）Host 地址配置（适用于Nginx代理等场景中更换了请求地址）

文档管理》个性化设置》Host设置

（4）更友好的API调试页面

页面分为【文档】【调试】【open】几个部分。

类似于 PostMan 可以分别设置请求头参数与请求体参数，支持多种不同的参数类型，不需要的参数可以删除。

（5）更强的 Json 支持

能够很清晰标准的展示 json 格式数据。

Json数据可以折叠。

最后：

更多拓展资料推荐阅读：
阿里架构师的Java知识地图（28个知识点），让我成了offer收割机
获取更多资源、知识分享、开源代码！

knife4j更多用法请请自己去官网发现，官网的文档讲得非常的详细， Knife4J官网。

四时宝库

程序员的知识宝库

Knife4j，拯救Swagger不那么美观的页面和差点意思的功能

前言：

正文

最后：