在現代的 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 官方文檔
希望這篇博客對你有所幫助，歡迎在評論區分享你的使用體驗或提出問題！🚀
