試試使用 eolinker 掃描 GitLab 代碼註釋自動生成 API 文檔？

前言：

通常寫完代碼以後，還要將各種參數註解寫入API文檔，方便後續進行對接和測試，這個過程一般都很麻煩，若是有工具能夠讀取代碼註釋直接生成API文檔的話，那會十分方便。
此前一直都是在使用eolinker的，但自從去年他們家「註釋生成文檔」的功能下線後，我就一直活在水深火熱當中——真的不想寫文檔啊，真的好累啊。
然而這兩天上線後，忽然發現這個功能從新上線了！必須給你們安利一波！
官網地址：https://www.eolinker.com
根據官方的解釋，這個功能簡單來講就是讀取 gitlab（之前應該還能讀本地代碼） 的 php 代碼（截至發文增長支持讀取java，更方便了）註釋生成 API 文檔。

下面是官方的操做介紹：

1.先在EOLINKER新建項目，隨後進入項目概況頁，能夠在概況頁中找到「掃描代碼註解生成文檔」模塊。

2.在同步以前咱們打開設置看下須要填寫什麼信息。

總共是10個選項，咱們來分別看下須要怎麼填寫：

• 1.代碼倉庫類型，如今默認只有gitlab，在官方羣問了他們的PM，後面應該還會支持github。
• 2.代碼倉庫地址，gitlab有線上版本和用戶本身搭建私有云版本，線上版本能夠填寫https://gitlab.com，若是是本身部署的gitlab寫域名或者IP端口。
• 3.項目ID，gitlab中新建項目後會有一個project ID，填入便可。
• 4.訪問私鑰，經過gitlab的Access Tokens功能可獲取，後面會詳細介紹如何獲取。
• 5.須要掃描的分支，默認爲master。咱們也能夠新建一個分支。
• 6.須要掃描的API目錄路徑，創建一個目錄做爲API目錄。
• 7.須要掃描的數據結構目錄路徑，創建一個目錄做爲數據結構目錄。
• 8.目標語言，目前默認只有PHP，比較惋惜只有一個語言，不過我跟他們客服聊天，說是後面更新的語言支持會增長java。
• 9.註解格式，默認爲Swagger 2.0，代碼註釋編寫的格式能夠按照下面的形式來寫，或者參考官方文檔http://zircote.com/swagger-php/annotations.html

好比model的

好比controller的

• 10.數據同步方式，目前可選增量更新、全量更新、僅添加新的API三種形式。以上就是須要填寫的所有信息。要正確填寫這些信息，接下來咱們就要轉到gitlab進行設置。

因爲官方沒有介紹過Gitlab，那仍是由我先介紹下比較合適：gitLab 是一個用於倉庫管理系統的開源項目，使用git做爲代碼管理工具，並在此基礎上搭建起來的web服務。gitlab跟github有點相似，都是基於web的git倉庫，關於註冊gitlab新建帳號如何操做的部分我就很少說了，但若是你已經有github帳號的話，是能夠用github帳號登陸gitLab的。

1.首先要新建項目，這裏我新建了一個名爲demo code的project。

2.新建後已經有一個master的分支，而後在分支下分別創建兩個新的目錄：我命名爲controllers和models，一個做爲API目錄路徑，一個做爲數據結構目錄路徑。

3.將寫好的php代碼上傳至分別的目錄。能夠直接用命令行或者直接將文件上傳。

4.成功上傳代碼後，跟着就是獲取密鑰。在gitlab中，生成密鑰須要用到Access Tokens功能。先進入設置頁面，經過左邊菜單中的Access Tokens功能，填寫對應的項目名稱，再根據須要，勾選開放的權限，看不懂也能夠按照我下面的截圖進行勾選，點擊綠框後就能夠獲取我的的密鑰了。以下圖：

5.進行到這一步，咱們已經把全部的信息都拿到了，再回到EOLINKER將信息填入，請看下圖，注意數據同步方式我選擇的是增量更新。

那我爲何會選擇增量更新呢？而三種數據同步更新區別是什麼呢？

• 增量更新：判斷已有API的詳細信息，添加新的API信息。用註解的數據替換掉現有的數據。部分註解沒有的數據，好比mock、參數值可能性、詳細文檔等等，均會保留。
• 全量更新：在添加新的API的基礎上，全量替換現有API內的信息，以註解的爲準，不保留註解沒有的數據。
• 僅添加新的API：判斷接口名稱是否已經存在，不存在則插入。

下面舉個例子介紹下三種數據同步更新的區別， GitLab中的接口只有參數，而導入 EOLINKER 後會有 mock、詳細文檔等數據。假如如今你的 GitLab 倉庫有 ABCD 四個接口，在 EOLINKER 有 A 一個接口。

• 採用「增量更新」後，EOLINKER 上將新增 BCD 三個接口；若是倉庫A接口的數據有所更新，那麼在保持原有本地A接口的 mock、詳細文檔數據的同時，本地亦將新增相應更新的數據；
• 採用「全量更新」後，EOLINKER 上將有 ABCD 四個接口；此時本地A 接口全部數據都不保留，而會與倉庫中A接口的數據保持一致；
• 採用「僅添加新的 API」後，EOLINKER將以接口名稱來判斷是否須要添加新的API，所以EOLINKER上將新增 BCD 三個接口；即使 GitLab 上的參數已經改變，但本地原有的A接口數據不變；

所以，不管是什麼狀況都推薦採用增量更新。不過即使你仍是誤操做了，EOLINKER都會自動生成API歷史版本，方便咱們回滾文檔，操做失誤也不怕了。

1.根據官方的說明，在設置完成點擊當即同步後，文檔即會開始進行同步，而同步生成文檔所需的時間，則根據代碼註釋的數據量來決定。

2.API文檔和對應的分組都被自動生成了，以下圖。

3.那咱們就能夠直接編輯修改文檔了，實在是方便了不少。

補充一句：按照他們的更新速度，目前也已經支持讀取gitlab上java代碼了，操做步驟跟讀取php的步驟相似，這裏就不展開說了，還不知道請回頭再看一遍文章hhh。

總結

若是能夠經過掃描代碼註釋自動生成API文檔，寫完代碼註解後就不用再一條一條的寫接口文檔，如今又有一個理由能夠再也不使用swagger了。新增的這個功能能夠減輕大部分沒必要要的工做量，雖然如今只能支持gitlab上的php代碼和java代碼，但後續確定還會繼續支持更多的平臺和編程語言代碼，持續使用起來將會更加方便和快捷，但願eolinker可以給咱們帶來更多的驚喜。官網地址：https://www.eolinker.com