swagger
前言：
Swagger现在已经成了最流行的接口文档生成与管理工具，但是你是否在用的时候也在吐槽，它是真的不好看，接口测试的json数据没法格式化，测试地址如果更改了还要去改配置，接口测试时增加token验证是真的麻烦......等等，拿什么拯救你，swagger同学！
针对Swagger的种种缺点，Knife4j就呼之欲出了。
正文：
一、先看一下它长什么样子吧
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 文档预览：
导出的MarkDown
Html 文档预览：
导出的Html
（3）Host 地址配置（适用于Nginx代理等场景中更换了请求地址）
文档管理》个性化设置》Host设置
Host地址配置
（4）更友好的API调试页面
页面分为【文档】【调试】【open】几个部分。
API接口调试
类似于 PostMan 可以分别设置请求头参数与请求体参数，支持多种不同的参数类型，不需要的参数可以删除。
API接口调试
（5）更强的 Json 支持
能够很清晰标准的展示 json 格式数据。
支持json格式化
Json数据可以折叠。
最后：
关注公众号【阳光的充能小站】，获取更多资源、知识分享、开源代码！
knife4j更多用法请请自己去官网发现，官网的文档讲得非常的详细， Knife4J官网。
image
网友评论