Api文檔自動生成工具

java開發，根據代碼自動生成api接口文檔工具，支持RESTful風格，今天咱們來學一下api-doc的生成

預覽

在線預覽地址

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

來源： https://www.jianshu.com/u/4ea...