一、引言：跟接口文檔說拜拜 👋

作為一名 Java 開發者，你是否還在為編寫繁瑣的 API 文檔而頭疼？傳統的手動編寫方式不僅耗時費力，而且容易出錯，難以維護。今天，我們就來介紹一款神器 Knife4j，它可以幫助你輕松生成美觀、易于使用的 API 文檔，讓你告別文檔編寫煩惱！

二、Knife4j 簡介：API 文檔界的“后起之秀”

簡單來說，Knife4j 是一個集 Swagger2 和 OpenAPI3 為一體的增強解決方案，它不僅擁有 Swagger 的所有功能，還做了很多優化和增強，例如：

• 界面更美觀： 提供簡潔美觀的界面，方便用戶瀏覽和使用 API 文檔。
• 功能更豐富： 支持接口排序、搜索、分組等功能，支持多種格式輸出。
• 易用性更高： 提供了更友好的配置方式，使用起來更加簡單方便。

三、Spring Boot 集成 Knife4j：三步搞定，輕松上手 🚀

1. 添加依賴：引入 Knife4j 包

在你的 Spring Boot 項目的 pom.xml 文件中添加以下依賴：

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

2. 配置 Knife4j：告訴它你的 API 信息

創建一個配置類，例如 Knife4jConfiguration，使用 @EnableSwagger2WebMvc 注解開啟 Swagger 功能，并配置 Docket Bean，就像這樣：

package com.muqing.common.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {@Bean(value = "mq-admin-api")public Docket defaultApi2() {Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("MQ-ADMIN API文檔").description("# 基于 Spring Boot 與 Vue3 的后臺管理系統。").termsOfServiceUrl("https://doc.uyii.cn/").contact("zhy@uyii.cn").version("1.0").build()).select().paths(PathSelectors.any()).build();return docket;}
}

3. 運行項目：見證奇跡的時刻 ?

啟動你的 Spring Boot 應用，在瀏覽器中訪問 http://localhost:8800/doc.html，你就能看到 Knife4j 生成的 API 文檔啦！

四、進階用法：玩轉 Knife4j，定制你的 API 文檔 🎨

• 分組管理 API 文檔：

  @Beanpublic Docket adminApi() {return new Docket(DocumentationType.SWAGGER_2).groupName("admin").select().apis(RequestHandlerSelectors.basePackage("com.muqing.admin")) // 修改為你的模塊包路徑.paths(PathSelectors.any()).build();}@Beanpublic Docket frontApi() {return new Docket(DocumentationType.SWAGGER_2).groupName("front").select().apis(RequestHandlerSelectors.basePackage("com.muqing.front")) // 修改為你的模塊包路徑.paths(PathSelectors.any()).build();}

• 自定義 API 信息：

@RestController
@RequestMapping("/users")
@Api(tags = "用戶管理")
public class UserController {@GetMapping("/{id}")@ApiOperation("獲取用戶信息")public User getUser(@PathVariable Long id) {// ...}
}

五、實戰演練：小試牛刀，鞏固學習成果 💪

我們來創建一個簡單的 Spring Boot 項目，演示如何使用 Knife4j 生成 API 文檔：

1. 創建一個 Spring Boot 項目，添加 Web 依賴和 Knife4j 依賴。

2. 創建一個 FrontIndexController，編寫接口：

package com.muqing.front.controller;import com.muqing.common.api.ApiResult;
import com.muqing.front.entity.Article;
import com.muqing.front.service.FrontIndexService;
import com.muqing.front.vo.IndexVo;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** IndexController** @author zhy* @since 2023/6/5*/
@RestController
@Api(tags = "后臺首頁")
@RequestMapping("/front")
public class FrontIndexController {@Autowiredprivate FrontIndexService frontIndexService;/*** 首頁博主信息** @return {@link ApiResult}<{@link IndexVo}>*/@ApiOperation("博主信息")@GetMapping()public ApiResult<IndexVo> index() {IndexVo IndexVo = frontIndexService.getAuthorInfo();return ApiResult.success(IndexVo);}/*** 關于我** @return {@link Article}*/@ApiOperation("關于我")@GetMapping("/about")public ApiResult<Article> about() {Article article = frontIndexService.getAbout();return ApiResult.success(article);}
}

3. 運行項目，訪問 http://localhost:8080/doc.html，查看生成的 API 文檔。

結語：API 文檔，從此輕松搞定 🎉

Knife4j 為我們提供了一種簡單高效的方式來生成和管理 API 文檔，從此告別繁瑣的手動編寫，讓前后端協作更加順暢！
希望這篇文章能夠幫助你快速上手 Knife4j，更多進階的技能請閱讀官方文檔！ 🎉

參考資料：學習永無止境 📚

• Knife4j 官方文檔
• Swagger 官方文檔

個人觀點，僅供參考，本文內容如有問題，歡迎留言討論。

---