仍然會使用eolinker掃描GitLab代碼注釋自動

本篇文章給大家分享的是有關(guān)仍然會使用eolinker掃描GitLab代碼注釋自動，小編覺得挺實(shí)用的，因此分享給大家學(xué)習(xí)，希望大家閱讀完這篇文章后可以有所收獲，話不多說，跟著小編一起來看看吧。

前言：

一般寫完代碼之后，還要將各類參數(shù)注解寫入API文檔，方便后續(xù)進(jìn)行對接和測試，這個過程通常都很麻煩，如果有工具可以讀取代碼注釋直接生成API文檔的話，那會十分方便。
此前一直都是在使用eolinker的，但自從去年他們家“注釋生成文檔”的功能下線后，我就一直活在水深火熱當(dāng)中——真的不想寫文檔啊，真的好累啊。
然而這兩天上線后，突然發(fā)現(xiàn)這個功能重新上線了！必須給大家安利一波！
根據(jù)官方的解釋，這個功能簡單來說就是讀取 gitlab（以前應(yīng)該還能讀本地代碼） 的 php 代碼（截至發(fā)文增加支持讀取java，更方便了）注釋生成 API 文檔。

下面是官方的操作介紹：

1.先在EOLINKER新建項(xiàng)目，隨后進(jìn)入項(xiàng)目概況頁，可以在概況頁中找到“掃描代碼注解生成文檔”模塊。

2.在同步之前我們打開設(shè)置看下需要填寫什么信息。

總共是10個選項(xiàng)，我們來分別看下需要怎么填寫：

• 1.代碼倉庫類型，現(xiàn)在默認(rèn)只有g(shù)itlab，在官方群問了他們的PM，后面應(yīng)該還會支持github。

• 2.代碼倉庫地址，gitlab有線上版本和用戶自己搭建私有云版本，線上版本可以填寫https://gitlab.com，如果是自己部署的gitlab寫域名或者IP端口。

• 3.項(xiàng)目ID，gitlab中新建項(xiàng)目后會有一個project ID，填入即可。

• 4.訪問私鑰，通過gitlab的Access Tokens功能可獲取，后面會詳細(xì)介紹如何獲取。

• 5.需要掃描的分支，默認(rèn)為master。我們也可以新建一個分支。

• 6.需要掃描的API目錄路徑，建立一個目錄作為API目錄。

• 7.需要掃描的數(shù)據(jù)結(jié)構(gòu)目錄路徑，建立一個目錄作為數(shù)據(jù)結(jié)構(gòu)目錄。

• 8.目標(biāo)語言，目前默認(rèn)只有PHP，比較可惜只有一個語言，不過我跟他們客服聊天，說是后面更新的語言支持會增加java。

• 9.注解格式，默認(rèn)為Swagger 2.0，代碼注釋編寫的格式可以按照下面的形式來寫，或者參考官方文檔http://zircote.com/swagger-php/annotations.html

比如model的

比如controller的

• 10.數(shù)據(jù)同步方式，目前可選增量更新、全量更新、僅添加新的API三種形式。以上就是需要填寫的全部信息。要正確填寫這些信息，接下來我們就要轉(zhuǎn)到gitlab進(jìn)行設(shè)置。

由于官方?jīng)]有介紹過Gitlab，那還是由我先介紹下比較合適：gitLab 是一個用于倉庫管理系統(tǒng)的開源項(xiàng)目，使用git作為代碼管理工具，并在此基礎(chǔ)上搭建起來的web服務(wù)。gitlab跟github有點(diǎn)類似，都是基于web的git倉庫，關(guān)于注冊gitlab新建賬號如何操作的部分我就不多說了，但如果你已經(jīng)有g(shù)ithub賬號的話，是可以用github賬號登錄gitLab的。

1.首先要新建項(xiàng)目，這里我新建了一個名為demo code的project。

2.新建后已經(jīng)有一個master的分支，然后在分支下分別建立兩個新的目錄：我命名為controllers和models，一個作為API目錄路徑，一個作為數(shù)據(jù)結(jié)構(gòu)目錄路徑。

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

4.成功上傳代碼后，跟著就是獲取密鑰。在gitlab中，生成密鑰需要用到Access Tokens功能。先進(jìn)入設(shè)置頁面，通過左邊菜單中的Access Tokens功能，填寫對應(yīng)的項(xiàng)目名稱，再根據(jù)需要，勾選開放的權(quán)限，看不懂也可以按照我下面的截圖進(jìn)行勾選，點(diǎn)擊綠框后就可以獲取個人的密鑰了。如下圖：

5.進(jìn)行到這一步，我們已經(jīng)把所有的信息都拿到了，再回到EOLINKER將信息填入，請看下圖，注意數(shù)據(jù)同步方式我選擇的是增量更新。

那我為什么會選擇增量更新呢？而三種數(shù)據(jù)同步更新區(qū)別是什么呢？

• 增量更新：判斷已有API的詳細(xì)信息，添加新的API信息。用注解的數(shù)據(jù)替換掉現(xiàn)有的數(shù)據(jù)。部分注解沒有的數(shù)據(jù)，比如mock、參數(shù)值可能性、詳細(xì)文檔等等，均會保留。

• 全量更新：在添加新的API的基礎(chǔ)上，全量替換現(xiàn)有API內(nèi)的信息，以注解的為準(zhǔn)，不保留注解沒有的數(shù)據(jù)。

• 僅添加新的API：判斷接口名稱是否已經(jīng)存在，不存在則插入。
  聽起來很繞，我們來舉個例子。Gitlab上的接口只有參數(shù)，而導(dǎo)入EOLINKER后會有mock、詳細(xì)文檔等數(shù)據(jù)。假如現(xiàn)在你的gitlab倉庫有ABCD四個接口數(shù)據(jù)，在EOLINKER有A一個接口數(shù)據(jù)。

下面舉個例子介紹下三種數(shù)據(jù)同步更新的區(qū)別， GitLab中的接口只有參數(shù)，而導(dǎo)入 EOLINKER 后會有 mock、詳細(xì)文檔等數(shù)據(jù)。假如現(xiàn)在你的 GitLab 倉庫有 ABCD 四個接口，在 EOLINKER 有 A 一個接口。

• 采用“增量更新”后，EOLINKER 上將新增 BCD 三個接口；如果倉庫A接口的數(shù)據(jù)有所更新，那么在保持原有本地A接口的 mock、詳細(xì)文檔數(shù)據(jù)的同時(shí)，本地亦將新增相應(yīng)更新的數(shù)據(jù)；

• 采用“全量更新”后，EOLINKER 上將有 ABCD 四個接口；此時(shí)本地A 接口所有數(shù)據(jù)都不保留，而會與倉庫中A接口的數(shù)據(jù)保持一致；

• 采用“僅添加新的 API”后，EOLINKER將以接口名稱來判斷是否需要添加新的API，因此EOLINKER上將新增 BCD 三個接口；即便 GitLab 上的參數(shù)已經(jīng)改變，但本地原有的A接口數(shù)據(jù)不變；

因此，無論是什么情況都推薦采用增量更新。不過即便你還是誤操作了，EOLINKER都會自動生成API歷史版本，方便我們回滾文檔，操作失誤也不怕了。

1.根據(jù)官方的說明，在設(shè)置完成點(diǎn)擊立即同步后，文檔即會開始進(jìn)行同步，而同步生成文檔所需的時(shí)間，則根據(jù)代碼注釋的數(shù)據(jù)量來決定。

2.API文檔和對應(yīng)的分組都被自動生成了，如下圖。

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

如果可以通過掃描代碼注釋自動生成API文檔，寫完代碼注解后就不用再一條一條的寫接口文檔，現(xiàn)在又有一個理由可以不再使用swagger了。

以上就是仍然會使用eolinker掃描GitLab代碼注釋自動，小編相信有部分知識點(diǎn)可能是我們?nèi)粘９ぷ鲿姷交蛴玫降摹ＯＭ隳芡ㄟ^這篇文章學(xué)到更多知識。更多詳情敬請關(guān)注億速云行業(yè)資訊頻道。