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

編寫(xiě)和維護(hù)API文檔這個(gè)事情，對(duì)于后端程序員來(lái)說(shuō)，是一件惱人但又不得不做的事情，我們都不喜歡寫(xiě)文檔，但除非項(xiàng)目前后端代碼都是自己寫(xiě)的，否則API文檔將是前后端協(xié)作中一個(gè)不可或缺的溝通界面。

既然不可避免，那就想辦法弄個(gè)輪子吧。人生苦短，必須偷懶。

無(wú)圖無(wú)真相，生成文檔的效果如下：

功能特性

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

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

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

入門(mén)

支持JDK：1.8+

快速開(kāi)始

第一步：添加依賴

maven:

<dependency>
<groupId>io.github.yedaxiagroupId>
<artifactId>japidocsartifactId>
<version>1.3version>
dependency>

gradle:

compile'io.github.yedaxia1.3'

第二步：配置參數(shù)

你可以在任意一個(gè)main入口運(yùn)行下面的代碼：

DocsConfigconfig=newDocsConfig();
config.setProjectPath("yourspringbootprojectpath");//項(xiàng)目根目錄
config.setProjectName("ProjectName");//項(xiàng)目名稱
config.setApiVersion("V1.0");//聲明該API的版本
config.setDocsPath("yourapidocspath");//生成API文檔所在目錄
config.setAutoGenerate(Boolean.TRUE);//配置自動(dòng)生成
Docs.buildHtmlDocs(config);//執(zhí)行生成文檔

如果沒(méi)有意外，執(zhí)行完上面的代碼后，你就可以在配置的目錄中看到生成的文檔了。

編碼規(guī)范

JApiDocs是通過(guò)解析Java源碼來(lái)實(shí)現(xiàn)的，要使得JApiDocs正確工作，需要你在項(xiàng)目中的Controller書(shū)寫(xiě)遵循一定的編碼規(guī)范。

你可以結(jié)合源碼中 SpringDemo 這個(gè)模塊來(lái)對(duì)照理解。

1. 添加必要的代碼注釋

其中類注釋會(huì)對(duì)應(yīng)到一級(jí)接口分組，你也可以通過(guò)@description來(lái)指定分組名稱；JApiDocs 會(huì)通過(guò) @param 來(lái)尋找接口參數(shù)和進(jìn)一步解析參數(shù)的內(nèi)容。

/**
*用戶接口
*/
@RequestMapping("/api/user/")
@RestController
publicclassUserController{

/**
*用戶列表
*@paramlistForm
*/
@RequestMapping(path="list",method={RequestMethod.GET,RequestMethod.POST})
publicApiResult>list(UserListFormlistForm){
returnnull;
}

/**
*保存用戶
*@paramuserForm
*/
@PostMapping(path="save")
publicApiResultsaveUser(@RequestBodyUserFormuserForm){
returnnull;
}

/**
*刪除用戶
*@paramuserId用戶ID
*/
@PostMapping("delete")
publicApiResultdeleteUser(@RequestParamLonguserId){
returnnull;
}
}

如果提交的表單是 application/x-www-form-urlencoded 類型的key/value格式，你可以在 SpringBoot 端通過(guò)在 @param 參數(shù)后添加字段解釋或者在相關(guān)的JavaBean對(duì)象里面添加解釋：

//直接在java的@param注解中
@paramuserId用戶ID

//在FormBean對(duì)象中
publicclassUserListFormextendsPageForm{
privateIntegerstatus;//用戶狀態(tài)
privateStringname;//用戶名
}

這種格式對(duì)于到文檔中的參數(shù)描述將是表格的形式：

如果提交的表單是 application/json 類型的json數(shù)據(jù)格式，對(duì)應(yīng) SpringBoot 中的 @RequestBody 注解，在文檔中則是 json 格式顯示：

{
"id":"long//用戶ID",
"name":"string//用戶名",
"phone":"long//電話",
"avatar":"string//頭像",
"gender":"byte//性別"
}

2. 接口聲明返回對(duì)象

我們知道，如果Controller聲明了@RestController，SpringBoot會(huì)把返回的對(duì)象直接序列成Json數(shù)據(jù)格式返回給前端。JApiDocs也利用了這一特性來(lái)解析接口返回的結(jié)果，但由于JApiDocs是靜態(tài)解析源碼的，因此你要明確指出返回對(duì)象的類型信息，JApiDocs支持繼承、泛型、循環(huán)嵌套等復(fù)雜的類解析。

比如上面的saveUser接口：

/**
*保存用戶
*@paramuserForm
*/
@PostMapping(path="save")
publicApiResultsaveUser(@RequestBodyUserFormuserForm){
returnnull;
}

ApiResult表明了該接口返回的數(shù)據(jù)結(jié)構(gòu)，經(jīng)過(guò)JApiDocs處理后是這樣的：

{
"code":"int",
"errMsg":"string",
"data":{
"userId":"string//用戶id",
"userName":"string//用戶名",
"friends":[
{
"userId":"string//用戶id",
"userName":"string//用戶名"
}
],
"readBooks":[
{
"bookId":"long//圖書(shū)id",
"bookName":"string//圖書(shū)名稱"
}
],
"isFollow":"boolean//是否關(guān)注"
}
}

如果你不是通過(guò)返回對(duì)象的形式，你也可以通過(guò)JApiDocs提供的@ApiDoc注解來(lái)聲明返回類型，你可以參考@ApiDoc章節(jié)的相關(guān)配置內(nèi)容。

3. 接口對(duì)象在源碼中

我們知道，經(jīng)過(guò)編譯后的 class 字節(jié)碼中是沒(méi)有注釋信息的，如果要通過(guò)反射字節(jié)碼的方式來(lái)實(shí)現(xiàn)，則不可避免要引入運(yùn)行時(shí)注解，這樣會(huì)增加使用成本， 考慮到這一點(diǎn)，JApiDocs 從第二個(gè)版本之后就改成了使用解析源碼的方式，而不是反射字節(jié)碼的思路來(lái)實(shí)現(xiàn)了，但這樣直接導(dǎo)致的缺陷就是：所有的 Form Bean (表單)對(duì)象和返回對(duì)象就必須在項(xiàng)目的源碼中，否則就無(wú)法解析了，如果你們項(xiàng)目的JavaBean對(duì)象是通過(guò)jar包的形式提供的， 那很遺憾，JApiDocs將無(wú)法支持。

高級(jí)配置

@ApiDoc

JApiDocs 默認(rèn)只導(dǎo)出聲明了@ApiDoc的接口，我們前面通過(guò)設(shè)置 config.setAutoGenerate(Boolean.TRUE) 來(lái)解除了這個(gè)限制。

如果你不希望把所有的接口都導(dǎo)出，你可以把autoGenerate設(shè)置關(guān)閉，在相關(guān)Controller類或者接口方法上通過(guò)添加@ApiDoc來(lái)確定哪些接口需要導(dǎo)出。

當(dāng)@ApiDoc聲明在接口方法上的時(shí)候，它還擁有一些更靈活的設(shè)置，下面我們來(lái)看一下：

• result: 這個(gè)可以直接聲明返回的對(duì)象類型，如果你聲明了，將會(huì)覆蓋SpringBoot的返回對(duì)象
• url: 請(qǐng)求URL，擴(kuò)展字段，用于支持非SpringBoot項(xiàng)目
• method: 請(qǐng)求方法，擴(kuò)展字段，用于支持非SpringBoot項(xiàng)目

例子：

@ApiDoc(result=AdminVO.class,url="/api/v1/admin/login2",method="post")

@Ignore

如果你不想導(dǎo)出對(duì)象里面的某個(gè)字段，可以給這個(gè)字段加上@Ignore注解，這樣JApiDocs導(dǎo)出文檔的時(shí)候就會(huì)自動(dòng)忽略掉了：

例子:

publicclassUserForm{
@Ignore
privateBytegender;//性別
}

自定義代碼模板

JApiDocs 除了支持文檔導(dǎo)出，目前也支持生成了 Android 和 iOS 的返回對(duì)象代碼，對(duì)應(yīng) Java 和 Object-C 語(yǔ)言， 如果你想修改代碼模板，可以通過(guò)以下的方法：

第一步：定義代碼模板

把源碼中l(wèi)ibrary項(xiàng)目resources目錄下的代碼模板拷貝一份，其中，IOS_表示 Object-C 代碼模板，JAVA_開(kāi)頭表示 Java代碼， 模板中類似${CLASS_NAME}的符號(hào)是替換變量，具體含義你可以結(jié)合生成的代碼進(jìn)行理解，然后按照你想要的代碼模板進(jìn)行修改即可。

第二步：選擇新的模板

通過(guò)DocsConfig配置模板路徑替換成新的模板：

docsConfig.setCodeTplPath("模板路徑");

添加更多功能

JApiDocs 提供了插件接口，你可以通過(guò)插件接口來(lái)實(shí)現(xiàn)更多豐富的功能，下面介紹如何添加插件：

第一步：實(shí)現(xiàn) IPluginSupport 接口

publicclassCustomPluginimplementsIPluginSupport{

@Override
publicvoidexecute(ListcontrollerNodeList){
//實(shí)現(xiàn)你自己的功能需求
}
}

第二步：添加插件

config.addPlugin(newCustomPlugin());