一個無需注解的SpringBoot API文檔生成神器

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

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

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

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

功能特性

1、代碼即文檔

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

2、支持導出HTML

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

3、同步導出客戶端Model代碼

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

4、更多特性

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

簡潔的文檔

再好用的東西，如果沒有文檔說明，別人也無從入手。為了讓大家盡快上手，JApiDocs準備了一份極簡的文檔說明，確保你在幾分鐘就能用上JApiDocs。

花5分鐘不到就能認識一個提高工作效率的工具，讓你把更多的時間花在更加有價值的事情上，你確認不看一下嗎？

• 倉庫地址：https://github.com/YeDaxia/JApiDocs

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

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

入門

支持JDK：1.8+

快速開始

第一步：添加依賴

maven:

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

gradle:

compile'io.github.yedaxia1.3'

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

你可以在任意一個main入口運行下面的代碼：

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

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

編碼規(guī)范

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

你可以結(jié)合源碼中 SpringDemo 這個模塊來對照理解。

1. 添加必要的代碼注釋

其中類注釋會對應到一級接口分組，你也可以通過@description來指定分組名稱；JApiDocs 會通過 @param 來尋找接口參數(shù)和進一步解析參數(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 端通過在 @param 參數(shù)后添加字段解釋或者在相關(guān)的JavaBean對象里面添加解釋：

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

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

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

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

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

2. 接口聲明返回對象

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

比如上面的saveUser接口：

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

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

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

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

3. 接口對象在源碼中

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

高級配置

@ApiDoc

JApiDocs 默認只導出聲明了@ApiDoc的接口，我們前面通過設置 config.setAutoGenerate(Boolean.TRUE) 來解除了這個限制。

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

當@ApiDoc聲明在接口方法上的時候，它還擁有一些更靈活的設置，下面我們來看一下：

• result: 這個可以直接聲明返回的對象類型，如果你聲明了，將會覆蓋SpringBoot的返回對象
• url: 請求URL，擴展字段，用于支持非SpringBoot項目
• method: 請求方法，擴展字段，用于支持非SpringBoot項目

例子：

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

@Ignore

如果你不想導出對象里面的某個字段，可以給這個字段加上@Ignore注解，這樣JApiDocs導出文檔的時候就會自動忽略掉了：

例子:

publicclassUserForm{
@Ignore
privateBytegender;//性別
}

自定義代碼模板

JApiDocs 除了支持文檔導出，目前也支持生成了 Android 和 iOS 的返回對象代碼，對應 Java 和 Object-C 語言， 如果你想修改代碼模板，可以通過以下的方法：

第一步：定義代碼模板

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

第二步：選擇新的模板

通過DocsConfig配置模板路徑替換成新的模板：

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

添加更多功能

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

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

publicclassCustomPluginimplementsIPluginSupport{

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

第二步：添加插件

config.addPlugin(newCustomPlugin());