再見 Swagger UI！國人開源了一款超好用的 API 文檔生成框架，Star 4.7K+，真香??！
點擊關(guān)注公眾號，Java干貨及時送達(dá)
背景
最近，棧長發(fā)現(xiàn)某些國內(nèi)的開源項目都使用到了 Knife4j 技術(shù)，看名字就覺得很鋒利啊！
是不是這樣的縮寫呢：
Knife4j = Knife for Java ？
Java 匕首？
看起來很牛逼的樣子，當(dāng)然，這是我簡單的猜測，從字面上并不能猜到它是干嘛用的！
那么它究竟是一個什么樣的框架呢？
Knife4j 簡介
Knife4j 的前身是 ?swagger-bootstrap-ui，其實就是一個純 Swagger UI 的皮膚項目，用過 Swagger 的應(yīng)該都知道，Swagger UI 是不怎么好用的，并不太適合國人，所以 swagger-bootstrap-ui 項目就誕生了。
swagger-bootstrap-ui 后面為了滿足許多個性化的需求，又加入了許多豐富的服務(wù)端特性，不再僅僅只是專注于前端 UI 皮膚了，所以又改名：knife4j。
取名 knife4j 是希望它能像一把匕首一樣小巧、輕量，并且功能強悍，更是希望它能成為 Swagger 接口文檔服務(wù)的通用性增強型解決方案。
Knife4j 由國人程序員蕭明于 2017 年開源，到現(xiàn)在已經(jīng) 4 年多了，看了下 Star 數(shù)已經(jīng)超過 4.7k+ 了：
Knife4j 還獲得了 GVP 項目稱號，即 Gitee 最有價值的開源項目，并且我發(fā)現(xiàn)現(xiàn)在越來越多的開源項目都在使用它，Swagger UI 可以扔掉了。。
官網(wǎng)地址：
https://doc.xiaominfo.com/knife4j/
開源地址：
https://gitee.com/xiaoym/knife4j
Knife4j 界面賞鑒
Knife4j 采用了 Vue + And Design Vue 組件進(jìn)行重寫，相關(guān)界面拿出來供大家賞鑒。
接口文檔顯示界面：
接口調(diào)試界面：
Swagger Models 功能：
支持導(dǎo)出離線 Markdown、Html：
knife4j 果然非常強大，整個界面基于左右菜單式的布局方式，支持多標(biāo)簽同時打開展示、切換，文檔和調(diào)試也更清晰，感覺更符合國人的操作習(xí)慣吧。。
Knife4j 實戰(zhàn)
knife4j 目前主要支持以 Java 開發(fā)為主，并且支持 Spring MVC、Spring Boot、Spring Cloud 框架的集成使用。
本文棧長就以 Spring Boot 為基礎(chǔ)實戰(zhàn)下吧：
Spring Boot 2.5.0 Knife4j 2.0.9 Maven 3.6.3 JDK 1.8
注意： 使用 Knife4j 2.0.6+ 版本，Spring Boot 的版本要求 2.2.x+
1、Knife4j 依賴引入
<dependency>
????<groupId>com.github.xiaoymingroupId>
????<artifactId>knife4j-spring-boot-starterartifactId>
????<version>2.0.9version>
dependency>
2、Knife4j 配置
開啟增強功能及基本的登錄認(rèn)證：
knife4j:
??#?開啟增強
??enable:?true
??#?開啟登錄認(rèn)證
??basic:
????enable:?true
????username:?test
????password:?test
支持個性化配置項，如接口地址、接口描述屬性、UI 增強等個性化配置功能：
/**
?*?Knife4j?配置類
?*?來源微信公眾號：Java技術(shù)棧
?*?作者：棧長
?*/
@Configuration
@EnableSwagger2WebMvc
public?class?Knife4jConfiguration?{
????@Bean(value?=?"defaultDocket")
????public?Docket?defaultDocket()?{
????????//?聯(lián)系人信息
????????Contact?contact?=?new?Contact("公眾號：Java技術(shù)棧",?"https://www.javastack.cn",?"[email protected]");
????????//?創(chuàng)建?Docket
????????Docket?docket?=?new?Docket(DocumentationType.SWAGGER_2)
????????????????.apiInfo(new?ApiInfoBuilder()
????????????????????????.title("Knife4j?測試")
????????????????????????.description("Knife4j?Test")
????????????????????????.termsOfServiceUrl("https://www.javastack.cn")
????????????????????????.contact(contact)
????????????????????????.version("1.0")
????????????????????????.build())
????????????????.groupName("1.x")
????????????????.select()
????????????????.apis(RequestHandlerSelectors.basePackage("cn.javastack.springboot.knife4j.api"))
????????????????.paths(PathSelectors.any())
????????????????.build();
????????return?docket;
????}
}
Spring Boot 基礎(chǔ)就不介紹了，送你一份《Spring Boot 學(xué)習(xí)筆記》，高清理論＋實戰(zhàn)版，照著學(xué)習(xí)，沒有不會的，最新版正在努力更新中，可以持續(xù)關(guān)注公眾號 Java技術(shù)棧，會第一時間分享給大家。
3、新增測試接口
新增兩個測試接口，一個登錄（POST），一個問好（GET）。
/**
?*?Knife4j?測試接口
?*?來源微信公眾號：Java技術(shù)棧
?*?作者：棧長
?*/
@Api(tags?=?"測試模塊")
@RestController
public?class?Knife4jController?{
????/**
?????*?Knife4j?測試接口問好
?????*?來源微信公眾號：Java技術(shù)棧
?????*?作者：棧長
?????*/
????@ApiImplicitParam(name?=?"name",?value?=?"名稱",?required?=?true)
????@ApiOperation(value?=?"公眾號Java技術(shù)棧向你問好！")
????@ApiOperationSupport(order?=?2,?author?=?"棧長")
????@GetMapping("/knife4j/hi")
????public?ResponseEntity?hello(@RequestParam(value?=?"name")?String?name)?{
????????return?ResponseEntity.ok("Hi:"?+?name);
????}
????/**
?????*?Knife4j?測試接口登錄
?????*?來源微信公眾號：Java技術(shù)棧
?????*?作者：棧長
?????*/
????@ApiImplicitParams({
????????????@ApiImplicitParam(name?=?"username",?value?=?"用戶名",?required?=?true),
????????????@ApiImplicitParam(name?=?"password",?value?=?"密碼",?required?=?true)
????})
????@ApiOperation(value?=?"接口登錄！")
????@ApiOperationSupport(order?=?1,?author?=?"棧長")
????@PostMapping("/knife4j/login")
????public?ResponseEntity?login(@RequestParam(value?=?"username")?String?username,
????????????????????????????????????????@RequestParam(value?=?"password")?String?password)?{
????????if?(StringUtils.isNotBlank(username)?&&?"javastack".equals(password))?{
????????????return?ResponseEntity.ok("登錄成功:"?+?username);
????????}
????????return?ResponseEntity.ok("用戶名或者密碼有誤:"?+?username);
????}
}
上面為了支持接口順序和接口作者，使用了 Knife4j 的 @ApiOperationSupport 注解，其他的均為 Swagger 自帶的注解，從該目錄下看還支持下面的注解：
更多可去官網(wǎng)進(jìn)行學(xué)習(xí)。
完整的 Demo 代碼就不一一帖了，本節(jié)教程所有實戰(zhàn)源碼已上傳到這個倉庫：
https://github.com/javastacks/spring-boot-best-practice
4、Knife4j 測試
啟動應(yīng)用，打開 Knife4j 文檔頁：
http://localhost:8080/doc.html
主頁會顯示一些已經(jīng)配置好的文檔參數(shù)及接口統(tǒng)計信息，并且在首頁模塊菜單中也看到了我們的測試模塊的兩個接口。
接口文檔：
調(diào)試一下：
這里棧長使用了接口排序、還有接口作者功能，另外還支持分組排序、自定義文檔、Swagger 資源保護(hù)、導(dǎo)出 Markdown、參數(shù)緩存等眾多強大功能，增強功能多達(dá) 29 項，有興趣的可以自行嘗試...
總結(jié)
好了，今天棧長給大家介紹了國人程序員開源的一款 Knife4j 項目，也就是 Swagger 的增強版，毫無疑問要比 Swagger UI 更強大，更好用，也符合國人的習(xí)慣！
如果你也在使用 Swagger，可以考慮使用 Knife4j，它不僅有更強大的 UI，更有多達(dá) 29 項的增強功能，它們并不是替代關(guān)系，就像 Mybatis Plus 和 Mybatis 的關(guān)系一樣，它能助你更進(jìn)一步提高開發(fā)生產(chǎn)力。
如果你也在使用 Knife4j，歡迎留言分享哦！
本節(jié)教程所有實戰(zhàn)源碼已上傳到這個倉庫：
https://github.com/javastacks/spring-boot-best-practice
好了，今天的分享就到這里了，后面棧長會分享更多好玩的 Java 技術(shù)和最新的技術(shù)資訊，關(guān)注公眾號Java技術(shù)棧第一時間推送，我也將主流 Java 面試題和參考答案都整理好了，在公眾號后臺回復(fù)關(guān)鍵字 "面試" 進(jìn)行刷題。
最后，覺得我的文章對你用收獲的話，動動小手，給個在看、轉(zhuǎn)發(fā)，原創(chuàng)不易，棧長需要你的鼓勵。
版權(quán)聲明： 本文系公眾號 "Java技術(shù)棧" 原創(chuàng)，原創(chuàng)實屬不易，轉(zhuǎn)載、引用本文內(nèi)容請注明出處，抄襲者一律舉報＋投訴，并保留追究其法律責(zé)任的權(quán)利。
關(guān)注Java技術(shù)?？锤喔韶?/strong>
