僅掃描gitlab上程式碼註釋自動生成API文件的工具？推薦試試eolinker吧

隔壁王書發表於2019-03-26
GitlabAPI

前言：

一般寫完程式碼之後，還要將各類引數註解寫入API文件，方便後續進行對接和測試，這個過程通常都很麻煩，如果有工具可以讀取程式碼註釋直接生成API文件的話，那會十分方便。 此前一直都是在使用eolinker的，但自從去年他們家“註釋生成文件”的功能下線後，我就一直活在水深火熱當中——真的不想寫文件啊，真的好累啊。 然而這兩天上線後，突然發現這個功能重新上線了！必須給大家安利一波！ 官網地址：www.eolinker.com 根據官方的解釋，這個功能簡單來說就是讀取 gitlab（以前應該還能讀原生程式碼） 的 php 程式碼（截至發文增加支援讀取java，更方便了）註釋生成 API 文件。

下面是官方的操作介紹：

1.先在EOLINKER新建專案，隨後進入專案概況頁，可以在概況頁中找到“掃描程式碼註解生成文件”模組。

圖1概況頁功能.png

2.在同步之前我們開啟設定看下需要填寫什麼資訊。

圖2同步需要填寫的資訊.png

總共是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的

程式碼截圖.png

比如controller的

程式碼截圖2.png

  • 10.資料同步方式，目前可選增量更新、全量更新、僅新增新的API三種形式。以上就是需要填寫的全部資訊。要正確填寫這些資訊，接下來我們就要轉到gitlab進行設定。

GITLAB

由於官方沒有介紹過Gitlab，那還是由我先介紹下比較合適：gitLab 是一個用於倉庫管理系統的開源專案，使用git作為程式碼管理工具，並在此基礎上搭建起來的web服務。gitlab跟github有點類似，都是基於web的git倉庫，關於註冊gitlab新建賬號如何操作的部分我就不多說了，但如果你已經有github賬號的話，是可以用github賬號登入gitLab的。

1.首先要新建專案，這裡我新建了一個名為demo code的project。

圖3新建專案.png

圖4新建demo.png

2.新建後已經有一個master的分支，然後在分支下分別建立兩個新的目錄：我命名為controllers和models，一個作為API目錄路徑，一個作為資料結構目錄路徑。

圖5在master下建立目錄.png

3.將寫好的php程式碼上傳至分別的目錄。可以直接用命令列或者直接將檔案上傳。

圖6上傳php程式碼.png

圖7三個php程式碼.png

4.成功上傳程式碼後，跟著就是獲取金鑰。在gitlab中，生成金鑰需要用到Access Tokens功能。先進入設定頁面，通過左邊選單中的Access Tokens功能，填寫對應的專案名稱，再根據需要，勾選開放的許可權，看不懂也可以按照我下面的截圖進行勾選，點選綠框後就可以獲取個人的金鑰了。如下圖：

圖8獲取個人金鑰.png

圖9個人金鑰.png

5.進行到這一步，我們已經把所有的資訊都拿到了，再回到EOLINKER將資訊填入，請看下圖，注意資料同步方式我選擇的是增量更新。

圖10資訊設定.png

那我為什麼會選擇增量更新呢？而三種資料同步更新區別是什麼呢？

  • 增量更新：判斷已有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.根據官方的說明，在設定完成點選立即同步後，文件即會開始進行同步，而同步生成文件所需的時間，則根據程式碼註釋的資料量來決定。

圖11點選立即同步.png

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

圖12API文件和分組被自動生成.png

3.那我們就可以直接編輯修改文件了，實在是方便了很多。

圖13編輯文件.png

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

總結

如果可以通過掃描程式碼註釋自動生成API文件，寫完程式碼註解後就不用再一條一條的寫介面文件，現在又有一個理由可以不再使用swagger了。新增的這個功能可以減輕大部分不必要的工作量，雖然現在只能支援gitlab上的php程式碼和java程式碼，但後續肯定還會繼續支援更多的平臺和程式語言程式碼，持續使用起來將會更加方便和快捷，希望eolinker能夠給我們帶來更多的驚喜。官網地址：www.eolinker.com

相關文章