java開發，根據代碼自動生成api接口文檔工具，支持RESTful風格，今天我們來學一下api-doc的生成
作者：互聯網編程。 歡迎投稿，一起交流技術
https://www.jianshu.com/u/4ea0af17fd67
預覽
在線預覽地址
http://lovepeng.gitee.io/apidoc
開發原理
這個工具是一個典型的前後端分離開發的項目，想了解前後端分離開發的同學也可以下載本項目學習。
項目後端使用java代碼，前端使用angular開發。Java開發時，使用註解把文檔相關信息標註在類的方法上，通過工具自動掃描代碼的註解，生成json數據，發給前端，前端angular解析生成頁面
本項目自帶一個spring-boot框架爲基礎的demo（這裏使用spring-boot做演示的demo僅僅是爲了方便，本質上只要是java寫的項目都可以用該工具），前端用angular做了一個比較漂亮的界面（最終前端界面都編譯成了html，如果你前端不熟悉，可以跳過，不用管他），這裏使用angular開發僅僅是我比較喜歡，你可以用任何你喜歡的的前端框架或者僅僅使用html寫一個漂亮的界面就可以。
後端項目開源地址：https://github.com/liepeng328/api-doc
前端開源地址：https://github.com/liepeng328/api-doc-angular
快速啓動
當成一個工具類用就可以了，下載本項目，拷貝包com.apidoc下的代碼到你的系統，
然後拷貝前端html頁面，在static.apidoc文件下，到你的資源文件下。即可使用
使用時，後臺提供兩個接口，目錄文檔接口和某個功能的詳細接口
//生成目錄接口
ApiDoc apiDoc = new GeneratorApiDoc()
.setInfo(//設置文檔基本信息
new ApiDocInfo()
.setTitle("某莫系統後臺管理文檔")
.setVersion("1.0")
.setDescription("")
)
.generator(packageName);//指定生成哪個包下controller的文檔
System.err.println(JsonUtil.toString(detail));
//詳細功能接口
ApiDocAction detail = new GeneratorApiDoc()
//設置數據庫連接信息，可忽略
.setDriver(driver)
.setUrl(url)
.setUserName(userName)
.setPassword(password)
.setDataBaseName(dataBaseName)
.getApiOfMethod(methodUUID);
System.err.println(JsonUtil.toString(detail));
一個詳細的例子
一個詳細例子如下代碼，這裏是springboot/springmvc的controller示例（展示兩個文檔，前端接口和後臺接口）參考代碼這個類 UserController.java
註解詳細介紹
共有6個註解，標註出整個文檔信息（我爲什麼講那麼詳細，那麼囉嗦，而且我沒有把這個項目打成jar包直接給別人使用，就是因爲文檔生成最大可能是需要特殊定製，確保你拿到該代碼可以個性化定製功能，隨意修改）。
- Api 標註文檔的功能模塊
- ApiAction 標註一個功能
- ApiReqAparams 請求參數
- ApiResqAparams 響應參數
- ApiParam 參數，用以組成請求參數和響應參數
- Table 用以標註實體類（比如bean）和數據庫表的關係，自動從數據庫讀取相關信息，不用寫大量的 ApiReqAparams和ApiResqAparams
詳細介紹如下
Api：寫在類上，表明一個功能模塊。
屬性：
- name 模塊名稱
- mapping url映射
ApiAction： 寫在方法上，表明一個功能點
屬性：
- name 方法的功能名稱
- mapping url映射
- description 描述
- method 請求方式（get，post，put，delete）
ApiReqParams： 請求參數
屬性：
- type：參數類型
- header 在請求頭
- url 在url後拼接
- form 表單數據
- json json格式
- ApiParam :參數列表
- value : class類，增加該類可自動讀取數據庫信息，避免寫多個屬性
- remove： 配合value使用，去除class類中無用的屬性，比如id
- dataType: 數據類型（字符串string,數字number,文件file,日期date,對象object,數組array,布爾類型boolean）
- descrption:描述
- defaultValue： 默認值
- required：是否必須
- object：從屬於哪個對象（因爲請求參數或者響應參數可能是對象中嵌套對象的，這裏爲了更好的表示這種層級關係，增加兩個屬性，object和belongTo，構建一個樹結構，表示對象之間無限、互相嵌套）
- belognTo ： 對應object 默認值爲"0"，字符串0
ApiRespParams： 響應參數
屬性：
- ApiParam： 該參數等同於請求參數中的ApiParam，參考如上描述
下載本項目並運行
配置jdk8以上版本，下載代碼，運行ApidocApplication類main方法即可。
然後訪問地址 http://localhost:8080/index.html
感謝列表
該項目爲maven項目，引用工具請查看 pom.xml
感謝 spring-boot
