在现代的 Web 开发中，API 文档是不可或缺的一部分。Knife4j 是基于 Swagger 的增强工具，它不仅提供了更友好的 API 文档界面，还支持更多实用的功能，如离线文档导出、全局参数配置等。本文将详细介绍如何在 Spring Boot 2 和 Spring Boot 3 中集成 Knife4j，并讲解其常用配置和注解的使用方法。
一、Knife4j 简介
Knife4j（原名 Swagger-Bootstrap-UI）是 Swagger 的增强版，提供了以下核心功能：
- 更友好的界面：美观、简洁的 API 文档展示。
- 增强功能：支持离线文档导出、全局参数、调试增强等。
- 兼容性：支持 Swagger 2 和 OpenAPI 3 规范。
- 易用性：通过简单配置即可快速集成。
二、Spring Boot 2 中使用 Knife4j
1. 依赖引入
在 pom.xml 中添加 Knife4j 的依赖：
<XML>
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version>
</dependency>2. 配置 Swagger
创建一个配置类，定义 Swagger 的基本信息：
<JAVA>
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 SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 扫描的包路径.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Knife4j Demo API").description("Spring Boot 2 with Knife4j Example").version("1.0").build();}
}3. 编写 Controller
创建一个示例 Controller，用于生成 API 文档：
<JAVA>
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/api")
@Api(tags = "示例模块")
public class DemoController {@GetMapping("/hello")@ApiOperation(value = "示例接口", notes = "返回一个简单的问候语")public String hello() {return "Hello, Knife4j!";}
}4. 访问 Knife4j 文档
启动项目，访问以下 URL：
- Knife4j 文档页面：http://localhost:8080/doc.html
- Swagger JSON 文档：http://localhost:8080/v2/api-docs
三、Spring Boot 3 中使用 Knife4j
1. 依赖引入
Spring Boot 3 使用 Jakarta EE 9+，因此需要引入 jakarta 版本的 Knife4j 依赖：
<XML>
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.2.0</version>
</dependency>2. 配置 OpenAPI
创建一个配置类，定义 OpenAPI 的基本信息：
<JAVA>
import io.swagger.v3.oas.models.OpenAPI;
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 customOpenAPI() {return new OpenAPI().info(new Info().title("Knife4j Demo API").version("1.0").description("Spring Boot 3 with Knife4j Example"));}
}3. 编写 Controller
创建一个示例 Controller，用于生成 API 文档：
<JAVA>
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/api")
@Tag(name = "示例模块", description = "示例模块 API")
public class DemoController {@GetMapping("/hello")@Operation(summary = "示例接口", description = "返回一个简单的问候语")public String hello() {return "Hello, Knife4j!";}
}4. 访问 Knife4j 文档
启动项目，访问以下 URL：
- Knife4j 文档页面：http://localhost:8080/doc.html
- OpenAPI 3 JSON 文档：http://localhost:8080/v3/api-docs
四、Knife4j 常用配置
1. 配置启用 Knife4j
在 application.yml 中配置：
<YAML>
knife4j:enable: true # 启用 Knife4jsetting:language: zh-CN # 界面语言为中文enable-swagger-models: true # 显示 Modelsenable-default-params: true # 启用默认参数2. 离线文档导出
Knife4j 支持将文档导出为 Markdown、HTML 或 Word 格式：
- 访问 Knife4j 文档页面。
- 点击右上角的“离线文档”按钮。
- 选择导出格式并下载。
3. 全局参数
在 Swagger 配置类中添加全局参数：
<JAVA>
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityScheme;@Bean
public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).securitySchemes(Collections.singletonList(new ApiKey("Authorization", "Authorization", "header"))).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();
}五、Knife4j 常用注解
1. 类级别注解
-
@Api（Swagger 2）(springboot2使用注解)：用于标识 API 模块的名称。<JAVA>
@Api(tags = "示例模块") -
@Tag（OpenAPI 3 (springboot3使用注解)）：用于标识 API 模块的名称。<JAVA>
@Tag(name = "示例模块", description = "示例模块 API")
2. 方法级别注解
-
@ApiOperation（Swagger 2）(springboot2使用注解)：用于描述 API 接口的详细信息。<JAVA>
@ApiOperation(value = "示例接口", notes = "返回一个简单的问候语") -
@Operation（OpenAPI 3）(springboot3使用注解)：用于描述 API 接口的详细信息。<JAVA>
@Operation(summary = "示例接口", description = "返回一个简单的问候语")
3. 参数级别注解
-
@ApiParam（Swagger 2）(springboot2使用注解)：用于描述 API 参数。<JAVA>
@ApiParam(name = "name", value = "用户名称", required = true) -
@Parameter（OpenAPI 3）(springboot3使用注解)：用于描述 API 参数。<JAVA>
@Parameter(name = "name", description = "用户名称", required = true)
六、总结
Knife4j 是 Swagger 的增强版，适合在 Spring Boot 项目中生成美观、功能强大的 API 文档。本文详细介绍了如何在 Spring Boot 2 和 Spring Boot 3 中集成 Knife4j，并讲解了常用配置和注解的使用方法。
如果你正在为 API 文档的生成和展示而烦恼，不妨试试 Knife4j，它会为你的开发工作带来极大的便利！😊
参考资源：
- Knife4j 官方文档
- Swagger 官方文档
希望这篇博客对你有所帮助，欢迎在评论区分享你的使用体验或提出问题！🚀
