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> 依赖引用

1.          <!--引入knife4j-->
2.         <dependency>
3.             <groupId>com.github.xiaoymin</groupId>
4.             <artifactId>knife4j-spring</artifactId>
5.             <version>3.0.3</version>
6.         </dependency>
7.         <dependency>
8.             <groupId>com.github.xiaoymin</groupId>
9.             <artifactId>knife4j-spring-ui</artifactId>
10.             <version>3.0.3</version>
11.         </dependency>

复制代码

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

创建配置文件Knife4jConfig.java

1. package com.nianxi.knife4j.config;
3. import org.springframework.context.annotation.Bean;
4. import org.springframework.context.annotation.Configuration;
5. import springfox.documentation.builders.ApiInfoBuilder;
6. import springfox.documentation.builders.PathSelectors;
7. import springfox.documentation.builders.RequestHandlerSelectors;
8. import springfox.documentation.service.ApiInfo;
9. import springfox.documentation.spi.DocumentationType;
10. import springfox.documentation.spring.web.plugins.Docket;
11. import springfox.documentation.swagger2.annotations.EnableSwagger2;
13. @Configuration
14. @EnableSwagger2
15. public class Knife4jConfig {
17.     //配置默认的接口
18.     @Bean
19.     public Docket defaultApi() {
20.         return new Docket(DocumentationType.SWAGGER_2)
21.                 .apiInfo(groupApiInfo())
22.                 .groupName("默认接口")
23.                 .select()
24.                 .apis(RequestHandlerSelectors.basePackage("com.nianxi.knife4j.controller"))
25.                 .paths(PathSelectors.any())
26.                 .build();
27.     }
29.     //配置分组
30.     private ApiInfo groupApiInfo(){
31.         return new ApiInfoBuilder()
32.                 .title("swagger-bootstrap-ui很棒~~~！！！")
33.                 .description("swagger-bootstrap-ui-demo RESTful APIs")
34.                 .termsOfServiceUrl("http://www.group.com/")
35.                 .version("1.0")
36.                 .build();
37.     }
38. }

复制代码

3> 配置静态文件

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

1. <?xml version="1.0" encoding="UTF-8"?>
2. <beans xmlns="http://www.springframework.org/schema/beans"
3.        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mvc="http://www.springframework.org/schema/mvc"
4.        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">
6.     <mvc:resources location="classpath:/META-INF/resources/" mapping="doc.html"/>
7.     <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
8. </beans>

复制代码

4> 配置web.xml文件

1. <!--1.该接口是springfox提供的Swagger实例接口-->
2. <servlet-mapping>
3.     <servlet-name>knife4jDemoMvc</servlet-name>
4.     <url-pattern>/v2/api-docs</url-pattern>
5. </servlet-mapping>
6. <!--2.该接口是springfox提供的Swagger分组接口-->
7. <servlet-mapping>
8.     <servlet-name>knife4jDemoMvc</servlet-name>
9.     <url-pattern>/swagger-resources</url-pattern>
10. </servlet-mapping>
11. <!--3.该接口是springfox提供的Swagger配置接口-->
12. <servlet-mapping>
13.     <servlet-name>knife4jDemoMvc</servlet-name>
14.     <url-pattern>/swagger-resources/configuration/ui</url-pattern>
15. </servlet-mapping>

复制代码

5> 启动测试
http://host:port/doc.html 

2. Spring Boot集成knife4j

 1> 依赖引用

1. <dependency>
2.             <groupId>com.github.xiaoymin</groupId>
3.             <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
4.             <version>4.4.0</version>
5.         </dependency>

复制代码

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

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

创建配置文件application.yml

1. springdoc:
2.   swagger-ui:
3.     path: /swagger-ui.html
4.     tags-sorter: alpha
5.     operations-sorter: alpha
6.   api-docs:
7.     path: /v3/api-docs
8.   group-configs:
9.     - group: '潘大佬'
10.       paths-to-match: '/**'
11.       #生成文档所需的扫包路径，一般为启动类目录
12.       packages-to-scan: com.nianxi.springboot02
15. #knife4j配置
16. knife4j:
17.   #是否启用增强设置
18.   enable: true
19.   #开启生产环境屏蔽
20.   production: false
21.   #是否启用登录认证
22.   basic:
23.     enable: true
24.     username: admin
25.     password: 123456
26.   setting:
27.     language: zh_cn
28.     enable-version: true
29.     enable-swagger-models: true
30.     swagger-model-name: 用户模块

复制代码

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

在config包下创建Knife4jConfig.java类

1. package com.nianxi.springboot02.config;
3. import io.swagger.v3.oas.models.OpenAPI;
4. import io.swagger.v3.oas.models.info.Contact;
5. import io.swagger.v3.oas.models.info.Info;
6. import org.springframework.context.annotation.Bean;
7. import org.springframework.context.annotation.Configuration;
9. @Configuration
10. public class Knife4jConfig {
11.     @Bean
12.     public OpenAPI springShopOpenApi() {
13.         return new OpenAPI()
14.                 // 接口文档标题
15.                 .info(new Info().title("潘大佬demo")
16.                         // 接口文档简介
17.                         .description("这是基于Knife4j OpenApi3的测试接口文档")
18.                         // 接口文档版本
19.                         .version("1.0版本")
20.                         // 开发者联系方式
21.                         .contact(new Contact().name("潘大佬")
22.                                 .email("1013909690@qq.com")));
24.     }
26. }

复制代码

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

在conrtoller包中创建UserController

1. package com.nianxi.springboot02.controller;
3. import com.nianxi.springboot02.entity.User;
4. import io.swagger.v3.oas.annotations.Operation;
5. import io.swagger.v3.oas.annotations.Parameter;
6. import io.swagger.v3.oas.annotations.Parameters;
7. import io.swagger.v3.oas.annotations.enums.ParameterIn;
8. import io.swagger.v3.oas.annotations.tags.Tag;
9. import org.springframework.http.ResponseEntity;
10. import org.springframework.web.bind.annotation.*;
12. @RestController
13. @RequestMapping("body")
14. @Tag(name = "body参数")
15. public class UserController {
17.     @Operation(summary = "普通body请求")
18.     @PostMapping("/body")
19.     public ResponseEntity<User> body(@RequestBody User user){
20.         return ResponseEntity.ok(user);
21.     }
23.     @Operation(summary = "普通body请求+Param+Header+Path")
24.     @Parameters({
25.             @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
26.             @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
27.             @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
28.     })
29.     @PostMapping("/bodyParamHeaderPath/{id}")
30.     public ResponseEntity<User> bodyParamHeaderPath(@PathVariable("id") String id, @RequestHeader("token") String token, @RequestParam("name")String name, @RequestBody User user){
31.         user.setName(user.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
32.         return ResponseEntity.ok(user);
33.     }
34. }

复制代码

5> 创建实体类

1. package com.nianxi.springboot02.entity;
3. import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
4. import io.swagger.v3.oas.annotations.media.Schema;
5. import lombok.Data;
7. @Data
8. public class User {
9.     @Schema(name = "用户名")
10.     private String name;
11.     private String id;
12.     private String age;
13.     private String emall;
14. }

复制代码

6> 最终依赖

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 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>
2.             <groupId>com.github.xiaoymin</groupId>
3.             <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
4.             <version>4.4.0</version>
5.         </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

用于描述实体类属性的描述、示例、验证规则等，比如 POJO 类及属性。
部门参数：

• name：名称
  
• title：标题
  
• description：描述
  
• example：示例值
  
• required：是否为必须
  
• format：属性的格式。如 @Schema(format = "email")
  
• maxLength 、 minLength：指定字符串属性的最大长度和最小长度
  
• maximum 、 minimum：指定数值属性的最大值和最小值
  
• pattern：指定属性的正则表达式模式
  
• type： 数据类型（integer，long，float，double，string，byte，binary，boolean，date，dateTime，password），必须是字符串。如 @Schema=(type="integer")
  
• implementation ：具体的实现类，可以是类本身，也可以是父类或实现的接口
  

---

@Content

内容注解。
部门参数：

• mediaType：内容的类型。比如：application/json
  
• schema：内容的模型界说，利用 @Schema 注解指定模型的相干信息。
  

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

复制代码

 

---

@Hidden

某个元素（API 操作、实体类属性等）是否在 API 文档中隐藏。
如，getUserById 方法不会显示在 API 文档中
 利用在实体类字段中，实现对敏感信息或不需要公开的元素进行隐藏。如：用户密码字段

---

@Operation

描述 API 操作的元数据信息。常用于 controller 上
部门参数：

• summary：简短描述
  
• description ：更具体的描述
  
• hidden：是否隐藏
  
• tags：标签，用于分组API
  
• operationId：操作的唯一标识符，发起利用唯一且具有描述性的名称
  
• parameters：指定相干的哀求参数，利用 @Parameter 注解来界说参数的具体属性。
  
• requestBody：指定哀求的内容，利用 @RequestBody 注解來指定哀求的类型。
  
• responses：指定操作的返回内容，利用 @ApiResponse 注解界说返回值的具体属性。
  

---

@Parameter

用于描述 API 操作中的参数
部门参数：

• name : 指定的参数名
  
• in：参数泉源，可选 query、header、path 或 cookie，默认为空，表示忽略
  
  
  
  • ParameterIn.QUERY 哀求参数
    
  • ParameterIn.PATH 路径参数
    
  • ParameterIn.HEADER header参数
    
  • ParameterIn.COOKIE cookie 参数
    
  
  
• description：参数描述
  
• required：是否必填，默认为 false
  
• schema ：参数的数据类型。如 schema = @Schema(type = "string")
  

---

@Parameters

包罗多个 @Parameter 注解，指定多个参数。
代码参考：
包罗了 param1 和 param2 两个参数

---

@RequestBody

API 哀求的注解

• description：哀求信息的描述
  
• content：哀求的内容
  
• required：是否必须
  

---

@ApiResponse

API 的响应信息。
部门参数：

• responseCode：响应的 HTTP 状态码
  
• description：响应信息的描述
  
• content：响应的内容
  

---

❤️❤️❤️

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。