api文檔自動生成工具

api-doc

java開發，根據代碼自動生成api接口文檔工具，支持RESTful風格

預覽

基本信息

演示

數據模擬mock

在線預覽地址

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

感謝@路曉磊 的工具類hutool https://gitee.com/loolly/hutool

感謝阿里fastjson