來(lái)自公眾號(hào)：漫畫(huà)編程
作者：葉大俠
JApiDocs是一個(gè)無(wú)需額外注解钦幔、開(kāi)箱即用的SpringBoot接口文檔生成工具。
編寫(xiě)和維護(hù)API文檔這個(gè)事情常柄，對(duì)于后端程序員來(lái)說(shuō)鲤氢，是一件惱人但又不得不做的事情，我們都不喜歡寫(xiě)文檔西潘，但除非項(xiàng)目前后端代碼都是自己寫(xiě)的卷玉，否則API文檔將是前后端協(xié)作中一個(gè)不可或缺的溝通界面。既然不可避免喷市，那就想辦法弄個(gè)輪子吧揍庄。人生苦短，必須偷懶东抹。
無(wú)圖無(wú)真相蚂子，生成文檔的效果如下：
相比Swagger要寫(xiě)一堆注解，Spring RestDocs需要寫(xiě)測(cè)試用例缭黔，才能生成API文檔食茎。JApiDocs 具有無(wú)痛集成的特點(diǎn)，你只需花幾分鐘就能知道它怎么用了馏谨。
快速開(kāi)始
要使得JApiDcos正確工作别渔，你寫(xiě)的代碼應(yīng)該是像下面的樣子的：
/**
* 用戶接口
*/
@RequestMapping("/api/user/")
@RestController
public class UserController {
/**
* 用戶列表
* @param listForm
*/
@RequestMapping(path = "list", method = {RequestMethod.GET, RequestMethod.POST} )
public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
return null;
}
/**
* 保存用戶
* @param userForm
*/
@PostMapping(path = "save")
public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
return null;
}
}
我們給Controller類和方法加上必要的注釋，給接口方法返回相關(guān)的對(duì)象類型惧互。是的哎媚，這樣JApiDocs就能解析到相關(guān)的接口信息了，就跟我們平時(shí)寫(xiě)的代碼是差不多的喊儡，但要注意拨与，你要通過(guò)@param來(lái)告訴JApiDocs接口的參數(shù)，但在IDE的幫助下艾猜，這個(gè)工作將是輕松愉悅的：
然后你在任意一個(gè)main入口方法執(zhí)行下面的代碼就可以生成文檔了：
DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 項(xiàng)目根目錄
config.setProjectName("ProjectName"); // 項(xiàng)目名稱
config.setApiVersion("V1.0"); // 聲明該API的版本
config.setDocsPath("your api docs path"); // 生成API 文檔所在目錄
config.setAutoGenerate(Boolean.TRUE); // 配置自動(dòng)生成
Docs.buildHtmlDocs(config); // 執(zhí)行生成文檔
接下來(lái)你只管好好寫(xiě)代碼买喧，生成Api文檔的工作就可以交給JApiDocs了捻悯，你不需要再為額外編寫(xiě)和維護(hù)文檔而煩惱。
功能特性
1淤毛、代碼即文檔
JApiDocs是通過(guò)直接解析SpringBoot的源碼語(yǔ)法來(lái)工作的今缚，所以只要Controller的語(yǔ)法符合一定的代碼規(guī)范，有合理的注釋低淡，就可以直接導(dǎo)出文檔姓言。
2、支持導(dǎo)出HTML
便捷的導(dǎo)航和接口查看界面蔗蹋；可本地預(yù)覽何荚，或者部署到HTTP服務(wù)器。推薦部署到服務(wù)器纸颜，方便前后端展開(kāi)協(xié)作兽泣。
3、同步導(dǎo)出客戶端Model代碼
支持導(dǎo)出Android端的 Java 和iOS端的 Object C Model代碼胁孙，減少前端程序員的重復(fù)編碼工作唠倦。
4、更多特性
支持接口搜索涮较；支持不同版本和英文文檔稠鼻；自定義擴(kuò)展等。
簡(jiǎn)潔的文檔
再好用的東西狂票，如果沒(méi)有文檔說(shuō)明候齿，別人也無(wú)從入手。為了讓大家盡快上手闺属，JApiDocs準(zhǔn)備了一份極簡(jiǎn)的文檔說(shuō)明慌盯，確保你在幾分鐘就能用上JApiDocs〉嗥鳎花5分鐘不到就能認(rèn)識(shí)一個(gè)提高工作效率的工具亚皂，讓你把更多的時(shí)間花在更加有價(jià)值的事情上，你確認(rèn)不看一下嗎国瓮？
倉(cāng)庫(kù)地址：https://github.com/YeDaxia/JApiDocs
