Knife4j的使用
Knife4j
一、是什么？
knife是一个接口文档的工具，是swagger的衍生产品。
官网地址：https://doc.xiaominfo.com/knife4j/
官方介绍：
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案
简洁
基于左右菜单式的布局方式,是更符合国人的操作习惯吧.文档更清晰…
个性化配置
个性化配置项,支持接口地址、接口description属性、UI增强等个性化配置功能…
增强
接口排序、Swagger资源保护、导出Markdown、参数缓存众多强大功能…
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开始,关于使用方法,请参考文档
二、为什么？
现在的大多数项目，都是前后端来发，这样就需要一个接口文档来完成前后端的协调，参数的选择，要不然两个人一直面对面沟通，成本很大，而且效率不高。
swagger是现在后端使用最多的一个接口文档。
而knife4j对swagger做了进一步封装，使其更适合国人的习惯于审美，而且功能更加强大。
三、怎么用?
1.导入依赖
<?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 http://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.6.1</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.rfx</groupId>
<artifactId>01-api</artifactId>
<version>1.0-SNAPSHOT</version>
<dependencies>
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
</project>
2.编写代码
配置类
package com.rfx.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import javax.swing.text.Document;
/**
* @author : tkz
* @date : 2021/12/20 10:38
*/
@Configuration
@EnableSwagger2
public class Knife4jConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("my knife4j api")
.description("my restful api")
.termsOfServiceUrl("www.baidu.com")
.contact(new Contact("sugar", "www.baidu.com", "1214877189@qq.com"))
.version("1.0")
.build())
.groupName("group 1.0")
.select()
.apis(RequestHandlerSelectors.basePackage("com.rfx.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
}
控制类
package com.rfx.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* @author : tkz
* @date : 2021/12/20 10:50
*/
@Api(tags = "欢迎接口")
@RestController
@RequestMapping("/hello")
public class HelloController {
@ApiOperation(value = "向客人问好")
@ApiImplicitParam(name = "name", value = "姓名", required = true)
@GetMapping
public ResponseEntity<String> hello(@RequestParam(value = "name") String name) {
return ResponseEntity.ok("hello " + name);
}
}
启动类
package com.rfx;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.core.env.ConfigurableEnvironment;
import java.net.InetAddress;
import java.net.UnknownHostException;
/**
* @author : tkz
* @date : 2021/12/20 11:03
*/
@SpringBootApplication
public class ApiApp {
static Logger logger = LoggerFactory.getLogger(ApiApp.class);
public static void main(String[] args) throws UnknownHostException {
ConfigurableApplicationContext ioc = SpringApplication.run(ApiApp.class, args);
ConfigurableEnvironment environment = ioc.getEnvironment();
String host = InetAddress.getLocalHost().getHostAddress();
String port = environment.getProperty("server.port");
logger.info("\n----------------------------------------------------------\n\t" +
"Application '{}' is running! Access URLs:\n\t" +
"Local: \t\thttp://localhost:{}\n\t" +
"External: \thttp://{}:{}\n\t"+
"Doc: \thttp://{}:{}/doc.html\n"+
"----------------------------------------------------------",
environment.getProperty("spring.application.name"),
port,
host,port,
host,port
);
}
}
配置文件
server:
port: 17709
spring:
application:
name: my-app
3.测试
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-mbacfwJl-1654574158716)(knife4j.assets\image-20211220114651710.png)]
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-ifhfWx2N-1654574158717)(knife4j.assets\image-20211220114744054.png)]
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-IKKGQe93-1654574158718)(knife4j.assets\image-20211220114814905.png)]
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-i7y4alD5-1654574158718)(knife4j.assets\image-20211220114841020.png)]
总结：
使用起来非常简单！！！
四、问题解决
启动项目后，发现报这个错误
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-RNPF2iaf-1654574158718)(knife4j.assets\image-20211220114934718.png)]
出现这个问题的原因是：springboot2.6.x以及上版本默认使用的PATH_PATTERN_PARSER而knife4j的springfox使用的是ANT_PATH_MATCHER导致的，springboot的yml文件配置url匹配规则
**解决办法:[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-qE5FfcT8-1654574158719)(knife4j.assets\image-20211220115203599.png)]
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
五、展望未来
如果我以后写项目的话，就将这个knife4j集成到我的项目中，多多学习这个东西。