干掉 Swagger (絲襪哥)，試試這個(gè)新工具！

點(diǎn)擊上方?好好學(xué)java?，選擇?星標(biāo)?公眾號(hào)

重磅資訊、干貨，第一時(shí)間送達(dá)

今日推薦：硬剛一周，3W字總結(jié)，一年的經(jīng)驗(yàn)告訴你如何準(zhǔn)備校招！

 個(gè)人原創(chuàng)100W+訪問量博客：點(diǎn)擊前往，查看更多

JApiDocs是一個(gè)無需額外注解、開箱即用的SpringBoot接口文檔生成工具。

編寫和維護(hù)API文檔這個(gè)事情，對(duì)于后端程序員來說，是一件惱人但又不得不做的事情，我們都不喜歡寫文檔，但除非項(xiàng)目前后端代碼都是自己寫的，否則API文檔將是前后端協(xié)作中一個(gè)不可或缺的溝通界面。既然不可避免，那就想辦法弄個(gè)輪子吧。人生苦短，必須偷懶。

無圖無真相，生成文檔的效果如下：

相比Swagger要寫一堆注解，Spring RestDocs需要寫測(cè)試用例，才能生成API文檔。JApiDocs 具有無痛集成的特點(diǎn)，你只需花幾分鐘就能知道它怎么用了。

快速開始

要使得JApiDcos正確工作，你寫的代碼應(yīng)該是像下面的樣子的：

/**
 * 用戶接口
 */
@RequestMapping("/api/user/")
@RestController
public class UserController {
    /**
     * 用戶列表
     * @param listForm
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
    public ApiResult> list(UserListForm listForm){
        return null;
    }

    /**
     * 保存用戶
     * @param userForm
     */
    @PostMapping(path = "save")
    public ApiResult saveUser(@RequestBody UserForm userForm){
        return null;
    }
}

我們給Controller類和方法加上必要的注釋，給接口方法返回相關(guān)的對(duì)象類型。是的，這樣JApiDocs就能解析到相關(guān)的接口信息了，就跟我們平時(shí)寫的代碼是差不多的，但要注意，你要通過@param來告訴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í)行生成文檔

接下來你只管好好寫代碼，生成Api文檔的工作就可以交給JApiDocs了，你不需要再為額外編寫和維護(hù)文檔而煩惱。

功能特性

1、代碼即文檔

JApiDocs是通過直接解析SpringBoot的源碼語法來工作的，所以只要Controller的語法符合一定的代碼規(guī)范，有合理的注釋，就可以直接導(dǎo)出文檔。

2、支持導(dǎo)出HTML

便捷的導(dǎo)航和接口查看界面；可本地預(yù)覽，或者部署到HTTP服務(wù)器。推薦部署到服務(wù)器，方便前后端展開協(xié)作。

3、同步導(dǎo)出客戶端Model代碼

支持導(dǎo)出Android端的 Java 和iOS端的 Object C Model代碼，減少前端程序員的重復(fù)編碼工作。

4、更多特性

支持接口搜索；支持不同版本和英文文檔；自定義擴(kuò)展等。

簡(jiǎn)潔的文檔

再好用的東西，如果沒有文檔說明，別人也無從入手。為了讓大家盡快上手，JApiDocs準(zhǔn)備了一份極簡(jiǎn)的文檔說明，確保你在幾分鐘就能用上JApiDocs。花5分鐘不到就能認(rèn)識(shí)一個(gè)提高工作效率的工具，讓你把更多的時(shí)間花在更加有價(jià)值的事情上，你確認(rèn)不看一下嗎？

倉(cāng)庫(kù)地址：https://github.com/YeDaxia/JApiDocs

中文文檔：https://japidocs.agilestudio.cn/#/zh-cn/

推薦文章

• 硬剛一周，3W字總結(jié)，一年的經(jīng)驗(yàn)告訴你如何準(zhǔn)備校招！
  

• 今年的校招，Java 好拿 offer 嗎？
  

• 10月了，該聊聊今年秋招了！
  

• 聊聊在騰訊實(shí)習(xí)快一個(gè)月的感受
  

原創(chuàng)電子書
歷時(shí)整整一年總結(jié)的?Java 面試 + Java 后端技術(shù)學(xué)習(xí)指南，這是本人這幾年及校招的總結(jié)，各種高頻面試題已經(jīng)全部進(jìn)行總結(jié)，按照章節(jié)復(fù)習(xí)即可，已經(jīng)拿到了大廠offer。
原創(chuàng)思維導(dǎo)圖
掃碼或者微信搜?程序員的技術(shù)圈子?回復(fù)?面試?領(lǐng)取原創(chuàng)電子書和思維導(dǎo)圖。