SpringBoot教程（十八） | SpringBoot集成knife4j（Swagger的UI增强工具）

Slow菜鸟

已于 2024-11-19 12:49:05 修改

阅读量1k

点赞数 12

分类专栏： # SpringBoot学习篇文章标签： knife4j spring boot

于 2024-07-29 10:25:41 首次发布

本文链接：https://blog.csdn.net/qq_20236937/article/details/140764412

版权

SpringBoot学习篇专栏收录该内容

37 篇文章

订阅专栏

SpringBoot教程（十八） | SpringBoot集成knife4j（Swagger的UI增强工具）

一、什么是Knife4j
二、Knife4j的发展史
三、SpringBoor整合Knife4j
扩展：其他主题皮肤
（1）绿色皮肤（swagger2 默认的）
（2）蓝色皮肤（bootstrap-ui）
（3）黑色皮肤
（4）蓝色皮肤
总结

一、什么是Knife4j

Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案，前身是 swagger-bootstrap-ui。它提供了更好的 API 文档展示界面和更多的功能特性。

Knife4j官方网站：https://doc.xiaominfo.com/

二、Knife4j的发展史

Knife4j的发展则与Swagger紧密相关：

早期阶段：swagger-bootstrap-ui作为Swagger UI的增强工具，提供了美化和增强的用户界面。
后续发展：随着Swagger的升级和迭代，swagger-bootstrap-ui也进入了2.x版本阶段，并更名为Knife4j。Knife4j不仅继承了swagger-bootstrap-ui的所有功能，还进行了更多的优化和增强，以满足用户的多样化需求。同时，Knife4j也支持OpenAPI 3.x规范，为开发者提供了更加全面和强大的API文档和测试工具。

在当今的开发实践中，当我们提及集成的API接口文档工具时，很多时候我们指的就是Knife4j。

三、SpringBoor整合Knife4j

1. 添加依赖

<!-- Spring Boot 2.x 使用以下依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

<!-- Spring Boot 3.x 使用以下依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

2. 配置文件

在 application.yml 中添加配置：

# Knife4j API文档配置文件
# 该配置文件定义了API文档的分组、扫描路径等信息

# SpringDoc配置
# SpringDoc是OpenAPI3的实现，用于自动生成API文档
springdoc:
  # Swagger UI配置
  swagger-ui:
    enabled: true                      # 启用Swagger UI界面
    path: /swagger-ui.html            # 设置Swagger UI访问路径
  
  # API文档配置
  api-docs:
    enabled: true                      # 启用API文档生成
    path: /v3/api-docs                # 设置API文档数据的访问路径
  
  # API分组配置
  # 通过分组可以将API接口按模块进行分类展示
  group-configs:
    # Kafka接口分组
    - group: 'Kafka接口'               # 分组名称
      paths-to-match: '/kafka/**'      # URL匹配模式
      packages-to-scan: com.example.springbootkafkaprovider.controller.kafka  # 要扫描的包路径
    
    # 系统接口分组
    - group: '系统接口'                # 分组名称
      paths-to-match: '/system/**'     # URL匹配模式
      packages-to-scan: com.example.springbootkafkaprovider.controller.system # 要扫描的包路径
    
    # 用户接口分组
    - group: '用户接口'                # 分组名称
      paths-to-match: '/user/**'       # URL匹配模式
      packages-to-scan: com.example.springbootkafkaprovider.controller.user   # 要扫描的包路径

# Knife4j增强配置
knife4j:
  enable: true                         # 启用Knife4j增强功能
  setting:
    language: zh_cn                    # 设置语言为中文
    enable-swagger-models: true        # 启用Swagger模型
    enable-document-manage: true       # 启用文档管理功能

# 访问地址说明：
# - Knife4j接口文档：http://localhost:8080/doc.html
# - OpenAPI原始数据：http://localhost:8080/v3/api-docs
# - Swagger UI：http://localhost:8080/swagger-ui.html

创建配置类

package com.example.springbootkafkaprovider.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;

/**
 * Knife4j API文档配置类
 * 
 * 该配置类用于设置API文档的基本信息，包括：
 * 1. 文档标题、版本、描述等基本信息
 * 2. 文档维护者联系方式
 * 3. 文档服务条款和许可证信息
 *
 * Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案，用于生成、描述、调试API文档
 *
 * @Configuration 标记这是一个配置类，会被Spring容器扫描并加载
 * @author your-name
 * @version 1.0
 * @since 2024-03
 */
@Configuration
public class Knife4jConfig {

    /**
     * 配置OpenAPI文档信息
     * 
     * 该Bean定义了API文档的元数据信息，包括：
     * 1. 文档标题 - 显示在文档页面顶部
     * 2. 文档版本 - API版本号
     * 3. 联系人信息 - 包括名称、邮箱和文档网站
     * 4. 文档描述 - 对整个API文档的概述
     *
     * OpenAPI规范是REST API文档的业界标准，
     * 通过这些配置可以生成规范的API文档界面
     *
     * @return OpenAPI 包含API文档配置信息的对象
     */
    @Bean
    public OpenAPI customOpenAPI() {
        // 配置联系人信息
        Contact contact = new Contact()
                .name("开发者")                           // 维护者姓名
                .email("your-email@example.com")         // 联系邮箱
                .url("https://doc.xiaominfo.com");       // 文档地址

        // 返回OpenAPI配置
        return new OpenAPI()
                .info(new Info()
                        .title("API文档")                // 文档标题
                        .version("v1.0")                // 文档版本
                        .contact(contact)               // 联系人信息
                        .description("API文档描述")      // 文档描述
                );
    }
}

3. 常用注解说明

类级别注解

@Tag(name = "模块名称", description = "模块描述")

方法级别注解

@Operation(summary = "接口名称", description = "详细描述")

参数注解

@Parameter(description = "参数描述", required = true)

实体类注解

@Schema(description = "实体描述")

4. 实战测试

在控制器中添加注解

@Tag(name = "用户管理", description = "用户管理相关接口")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @Operation(summary = "创建用户", description = "创建新用户")
    @PostMapping("/create")
    public ResponseEntity<User> createUser(
            @Parameter(description = "用户信息", required = true)
            @RequestBody User user) {
        // 实现逻辑
        return ResponseEntity.ok(user);
    }

    @Operation(summary = "获取用户信息")
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id) {
        // 实现逻辑
        return ResponseEntity.ok(new User());
    }
}

实体类注解示例

@Schema(description = "用户实体")
public class User {
    
    @Schema(description = "用户ID")
    private Long id;
    
    @Schema(description = "用户名", required = true)
    private String username;
    
    @Schema(description = "邮箱")
    private String email;
    
    // getter 和 setter
}

5. 访问文档

启动项目后，可以通过以下地址访问接口文档：

Knife4j 接口文档：http://localhost:8080/doc.html
OpenAPI 原始数据：http://localhost:8080/v3/api-docs
Swagger UI：http://localhost:8080/swagger-ui.html

6. 注意事项

版本兼容

Spring Boot 2.x 使用 knife4j-openapi3-spring-boot-starter
Spring Boot 3.x 使用 knife4j-openapi3-jakarta-spring-boot-starter

常见问题

如果访问 /doc.html 出现 404，检查 knife4j.enable 配置是否为 true
如果接口没有显示，检查包扫描路径是否正确
如果出现跨域问题，需要添加跨域配置

安全配置

生产环境建议关闭或设置访问密码
可以通过配置文件控制是否启用文档

7. 高级配置

1. 生产环境禁用

knife4j:
  production: true  # 开启生产环境屏蔽

2. 配置访问密码

knife4j:
  basic:
    enable: true
    username: admin
    password: 123456

3. 自定义响应消息

@Operation(summary = "创建用户", responses = {
    @ApiResponse(responseCode = "200", description = "创建成功"),
    @ApiResponse(responseCode = "400", description = "参数错误"),
    @ApiResponse(responseCode = "500", description = "服务器错误")
})

8. 最佳实践

合理分组：使用 @Tag 对接口进行分组
详细描述：为每个接口和参数添加清晰的描述
示例数据：提供请求和响应的示例
错误码：统一定义并文档化错误码
版本控制：通过配置管理 API 版本

通过以上步骤和配置，您就可以在 Spring Boot 项目中集成并使用 Knife4j 了。它将为您的项目提供一个漂亮的 API 文档界面，并且支持在线调试功能。

扩展：其他主题皮肤

（1）绿色皮肤（swagger2 默认的）

swagger2 默认的访问 http://localhost:8080/swagger-ui.html

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.10.0</version>
</dependency>

（2）蓝色皮肤（bootstrap-ui）

bootstrap-ui 访问 http://localhost:8080/doc.html

<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

（3）黑色皮肤

Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

（4）蓝色皮肤

mg-ui 访问 http://localhost:8080/document.html

<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

总结

目前还是 Knife4j 好用，页面上表现的更高级，功能上也更完善多样