前言：
一般寫完代碼之后，還要將各類參數注解寫入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