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

2021-03-22 本文已影响0人阳光的充能小站

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）启动项目，查看效果。