Knife4j的介绍与使用

一. 简介

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

gitee地址：https://gitee.com/xiaoym/knife4j

官方文档：https://doc.xiaominfo.com/

效果演示：http://knife4j.xiaominfo.com/doc.html

是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

对于当前最新的Spring Boot 3有以下注意

• Spring Boot 3 只支持OpenAPI3规范
• Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
• JDK版本必须 >= 17

作用

该UI增强包主要包括两大核心功能：文档说明 和 在线调试

• 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。
• 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简介、强大。
• 个性化配置：通过个性化ui配置项，可自定义UI的相关显示信息
• 离线文档：根据标准规范，生成的在线markdown离线文档，开发者可以进行拷贝生成markdown接口文档，通过其他第三方markdown转换工具转换成html或pdf，这样也可以放弃swagger2markdown组件
• 接口排序：自1.8.5后，ui支持了接口排序功能，例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序，step化接口操作，方便其他开发者进行接口对接

优势

knife4j 是 Swagger 生成 API 文档的增强解决方案，knife4j 对原生 swagger 的增强体现在：

• 提供了新的一套 Web 页面，更符合绝大多数人的使用习惯和审美；
• 补充了一些注解，扩展了原生 Swagger 的功能；
• 提供了动态字段注释功能来实现 Map 来接收参数这个的接口文档生成；
• 忽略参数属性来实现同一个实体类对不同接口生成不同的文档等诸如此类的小改进。

二. 基本使用

1. SpringMVC集成knife4j

1> 依赖引用

         <!--引入knife4j--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring</artifactId><version>3.0.3</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-ui</artifactId><version>3.0.3</version></dependency>

2> 创建配置文件(核心为Swagger)

创建配置文件Knife4jConfig.java

package com.nianxi.knife4j.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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class Knife4jConfig {//配置默认的接口@Beanpublic Docket defaultApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(groupApiInfo()).groupName("默认接口").select().apis(RequestHandlerSelectors.basePackage("com.nianxi.knife4j.controller")).paths(PathSelectors.any()).build();}//配置分组private ApiInfo groupApiInfo(){return new ApiInfoBuilder().title("swagger-bootstrap-ui很棒~~~！！！").description("swagger-bootstrap-ui-demo RESTful APIs").termsOfServiceUrl("http://www.group.com/").version("1.0").build();}
}

3> 配置静态文件

由于knife4j是通过webjar的方式提供服务,因此对外访问的doc.html需要在我们的mvc环境中配置静态目录,否则会出现404，在spring.xml主容器的配置文件中配置, 

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mvc="http://www.springframework.org/schema/mvc"xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/mvc https://www.springframework.org/schema/mvc/spring-mvc.xsd"><mvc:resources location="classpath:/META-INF/resources/" mapping="doc.html"/><mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
</beans>

4> 配置web.xml文件

<!--1.该接口是springfox提供的Swagger实例接口-->
<servlet-mapping><servlet-name>knife4jDemoMvc</servlet-name><url-pattern>/v2/api-docs</url-pattern>
</servlet-mapping>
<!--2.该接口是springfox提供的Swagger分组接口-->
<servlet-mapping><servlet-name>knife4jDemoMvc</servlet-name><url-pattern>/swagger-resources</url-pattern>
</servlet-mapping>
<!--3.该接口是springfox提供的Swagger配置接口-->
<servlet-mapping><servlet-name>knife4jDemoMvc</servlet-name><url-pattern>/swagger-resources/configuration/ui</url-pattern>
</servlet-mapping>

5> 启动测试

http://host:port/doc.html 

2. Spring Boot集成knife4j

 1> 依赖引用

 <dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

注意，我这里springBoot的版本为3.3.2 

2> 创建配置文件(核心为Swagger)

创建配置文件application.yml

springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: '潘大佬'paths-to-match: '/**'#生成文档所需的扫包路径，一般为启动类目录packages-to-scan: com.nianxi.springboot02#knife4j配置
knife4j:#是否启用增强设置enable: true#开启生产环境屏蔽production: false#是否启用登录认证basic:enable: trueusername: adminpassword: 123456setting:language: zh_cnenable-version: trueenable-swagger-models: trueswagger-model-name: 用户模块

3> 配置接口文档简介(Knife4jConfig)

在config包下创建Knife4jConfig.java类

package com.nianxi.springboot02.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class Knife4jConfig {@Beanpublic OpenAPI springShopOpenApi() {return new OpenAPI()// 接口文档标题.info(new Info().title("潘大佬demo")// 接口文档简介.description("这是基于Knife4j OpenApi3的测试接口文档")// 接口文档版本.version("1.0版本")// 开发者联系方式.contact(new Contact().name("潘大佬").email("1013909690@qq.com")));}}

4> 配置要显示的内容，即application.yml里面扫描路径的contriller包

在conrtoller包中创建UserController

package com.nianxi.springboot02.controller;import com.nianxi.springboot02.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class UserController {@Operation(summary = "普通body请求")@PostMapping("/body")public ResponseEntity<User> body(@RequestBody User user){return ResponseEntity.ok(user);}@Operation(summary = "普通body请求+Param+Header+Path")@Parameters({@Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),@Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),@Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)})@PostMapping("/bodyParamHeaderPath/{id}")public ResponseEntity<User> bodyParamHeaderPath(@PathVariable("id") String id, @RequestHeader("token") String token, @RequestParam("name")String name, @RequestBody User user){user.setName(user.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);return ResponseEntity.ok(user);}
}

5> 创建实体类

package com.nianxi.springboot02.entity;import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;@Data
public class User {@Schema(name = "用户名")private String name;private String id;private String age;private String emall;
}

6> 最终依赖

<?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>3.3.2</version><relativePath/> <!-- lookup parent from repository --></parent><groupId>com.nianxi</groupId><artifactId>SpringBoot-02</artifactId><version>0.0.1-SNAPSHOT</version><name>SpringBoot-02</name><description>SpringBoot-02</description><url/><licenses><license/></licenses><developers><developer/></developers><scm><connection/><developerConnection/><tag/><url/></scm><properties><java.version>17</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web-services</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency></dependencies><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><configuration><excludes><exclude><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></exclude></excludes></configuration></plugin></plugins></build></project>

7> 运行启动类，浏览器搜索localhost:8080/doc.html

三. 注解说明(OpenAPI3规范)

OpenAPI 规范 (中文版) (apifox.cn)

@Tag

用于说明或定义的标签。

部分参数：

• name：名称
• description：描述

@Schema

@Content

@RequestBody(content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))) 
@PostMapping("/users")
public void createUser(User user) {// ...
}

@ApiResponse