本申請涉及web應(yīng)用開發(fā)技術(shù)領(lǐng)域，特別涉及一種自動生成api文檔的方法及系統(tǒng)。

背景技術(shù)：

隨著時代的發(fā)展，人們更多地使用智能移動終端上安裝的各種應(yīng)用程序(app)獲取各種信息，其中很多app都會有自己的云服務(wù)后臺，或用來由app自身自動獲取新的信息并實時更新，或是由后臺開發(fā)人員進行信息的更新或在線不停機的修復(fù)一些小的bug。

當(dāng)前，作為做部分app和云服務(wù)后臺之間的標準連接方式，restapi(rest即表述性狀態(tài)傳遞，英文全稱：representationalstatetransfer，是一種針對網(wǎng)絡(luò)應(yīng)用的設(shè)計和開發(fā)方式，可以降低開發(fā)的復(fù)雜性，提高系統(tǒng)的可伸縮性的一種軟件架構(gòu)風(fēng)格；api即應(yīng)用程序編程接口，英文全稱：applicationprogramminginterface)已經(jīng)得到了絕大部分app開發(fā)者的認可并已經(jīng)開始廣泛的應(yīng)用，尤其是在近些年中，隨著新型api經(jīng)濟模式的逐漸興起，許多開發(fā)者廠商紛紛將自己的后臺業(yè)務(wù)能力作為restapi開放出來，給更廣泛的第三方開發(fā)者使用。

但是，在進行開發(fā)一個大型app時，不可避免的會致使開發(fā)團隊異常龐大，往往會出現(xiàn)后臺工程師所編寫的代碼無法被前端工程師理解清楚，而兩者之間的交流是一個非常費時費力的過程，再加上若開發(fā)需求變動、溝通不及時等情況出現(xiàn)，很容易出現(xiàn)后臺工程師發(fā)布的app版本與前端工程師看到的版本不一致的問題。

在現(xiàn)行的管理方法中，主要通過后端工程師為代碼段書寫注釋并一次次通過apidoc工具(一種提取apidoc注釋格式并生成api文檔的軟件)生成相應(yīng)的api文檔將其發(fā)送給前端工程師，隨著修改次數(shù)的增多，也依然會出現(xiàn)上述問題，那么，如何在無法避免需要重復(fù)生成最新版api文檔的前提下，提供一種更合理、更及時、不遺漏的以及非手動生成的自動生成最新版api文檔機制，是本領(lǐng)域技術(shù)人員亟待解決的問題。

技術(shù)實現(xiàn)要素：

本申請的目的是提供一種自動生成api文檔的方法及系統(tǒng)，能夠以一個更加合理、更及時的方法來消除因重復(fù)修改出現(xiàn)的遺漏生成最新版api文檔的潛在隱患、提升后臺與前端工程師之間的工作效率。

為解決上述技術(shù)問題，本申請?zhí)峁┮环N自動生成api文檔的方法，該方法包括：

對原始后臺代碼執(zhí)行附加apidoc注釋的處理，得到附加所述apidoc注釋的后臺代碼；其中，所述apidoc注釋為按照apidoc的注釋標簽格式書寫的；

對所述后臺代碼利用apidoc工具生成對應(yīng)的api文檔；

當(dāng)所述后臺代碼被修改時，相應(yīng)的修改所述apidoc注釋，得到最新版后臺代碼；

將所述最新版后臺代碼合并進git庫，并根據(jù)預(yù)設(shè)腳本調(diào)用預(yù)設(shè)命令生成最新版api文檔。

可選的，將所述最新版后臺代碼合并進git庫，并根據(jù)預(yù)設(shè)腳本調(diào)用預(yù)設(shè)命令生成最新版api文檔，包括：

當(dāng)所述最新版后臺代碼合并進git庫時，觸發(fā)shell腳本調(diào)用所述apidoc工具；

通過所述apidoc工具生成所述最新版api文檔至指定的服務(wù)器路徑下；

所述shell腳本將所述最新版api文檔從所述服務(wù)器路徑下復(fù)制到用戶閱讀路徑下。

可選的，利用所述apidoc工具生成所述最新版api文檔至指定的服務(wù)器路徑下，包括：

利用所述apidoc工具生成靜態(tài)且為html格式的所述最新版api文檔至指定的服務(wù)器路徑下。

可選的，在為原始后臺代碼進行添加apidoc注釋的處理前，還包括：

在git庫的服務(wù)器上安裝node.js環(huán)境，并在聯(lián)網(wǎng)情況下安裝所述apidoc工具。

本申請還提供了一種生成api文檔的系統(tǒng)，該系統(tǒng)包括：

添加注釋單元，用于對原始后臺代碼執(zhí)行附加apidoc注釋的處理，得到附加所述apidoc注釋的后臺代碼；其中，所述apidoc注釋為按照apidoc的注釋標簽格式書寫的；

第一生成單元，用于對所述后臺代碼利用apidoc工具生成對應(yīng)的api文檔；

修改單元，用于當(dāng)所述后臺代碼被修改時，相應(yīng)的修改所述apidoc注釋，得到最新版后臺代碼；

第二生成單元，用于將所述最新版后臺代碼合并進git庫，并根據(jù)預(yù)設(shè)腳本調(diào)用預(yù)設(shè)命令生成最新版api文檔。

可選的，所述第二生成單元包括：

腳本觸發(fā)子單元，用于當(dāng)所述最新版后臺代碼合并進git庫時，觸發(fā)shell腳本調(diào)用所述apidoc工具；

生成子單元，用于通過所述apidoc工具生成所述最新版api文檔至指定的服務(wù)器路徑下；

復(fù)制轉(zhuǎn)移子單元，用于所述shell腳本將所述最新版api文檔從所述服務(wù)器路徑下復(fù)制到用戶閱讀路徑下。

可選的，所述生成子單元具體為：

利用所述apidoc工具生成靜態(tài)且為html格式的所述最新版api文檔至指定的服務(wù)器路徑下的子單元。

可選的，還包括：

環(huán)境安裝單元，用于在git庫的服務(wù)器上安裝node.js環(huán)境，并在聯(lián)網(wǎng)情況下安裝所述apidoc工具。

本申請所提供的自動生成api文檔的方法，通過對原始后臺代碼執(zhí)行附加apidoc注釋的處理，得到附加所述apidoc注釋的后臺代碼；其中，所述apidoc注釋為按照apidoc的注釋標簽格式書寫的；對所述后臺代碼利用apidoc工具生成對應(yīng)的api文檔；當(dāng)所述后臺代碼被修改時，相應(yīng)的修改所述apidoc注釋，得到最新版后臺代碼；將所述最新版后臺代碼合并進git庫，并根據(jù)預(yù)設(shè)腳本調(diào)用預(yù)設(shè)命令生成最新版api文檔。

顯然，本申請所提供的技術(shù)方案通過自動將后臺工程師修改后的最新版后臺代碼及時生成最新版api文檔，以使前端工程師能夠及時且不遺漏的得到最新的api文檔。因此，能夠以更加合理、更加及時的生成api文檔的方法來消除因重復(fù)修改出現(xiàn)的遺漏生成最新版api文檔的潛在隱患、提升后臺與前端工程師之間的工作效率。本申請同時還提供了一種自動生成api文檔的系統(tǒng)，具有上述有益效果，在此不再贅述。

附圖說明

為了更清楚地說明本申請實施例或現(xiàn)有技術(shù)中的技術(shù)方案，下面將對實施例或現(xiàn)有技術(shù)描述中所需要使用的附圖作簡單地介紹，顯而易見地，下面描述中的附圖僅僅是本申請的實施例，對于本領(lǐng)域普通技術(shù)人員來講，在不付出創(chuàng)造性勞動的前提下，還可以根據(jù)提供的附圖獲得其他的附圖。

圖1為本申請實施例所提供的一種自動生成api文檔的方法的流程圖；

圖2為本申請實施例所提供的另一種自動生成api文檔的方法的流程圖；

圖3為本申請實施例所提供的又一種自動生成api文檔的方法的流程圖；

圖4為本申請實施例所提供的一種自動生成api文檔的方法系統(tǒng)的結(jié)構(gòu)圖。

具體實施方式

本申請的核心是提供一種自動生成api文檔的方法及系統(tǒng)，能夠以一個更加合理、更及時的方法來消除因重復(fù)修改出現(xiàn)的遺漏生成最新版api文檔的潛在隱患、提升后臺與前端工程師之間的工作效率。

為使本申請實施例的目的、技術(shù)方案和優(yōu)點更加清楚，下面將結(jié)合本申請實施例中的附圖，對本申請實施例中的技術(shù)方案進行清楚、完整地描述，顯然，所描述的實施例是本申請一部分實施例，而不是全部的實施例?；诒旧暾堉械膶嵤├?，本領(lǐng)域普通技術(shù)人員在沒有做出創(chuàng)造性勞動前提下所獲得的所有其他實施例，都屬于本申請保護的范圍。

以下結(jié)合圖1，圖1為本申請實施例所提供的一種自動生成api文檔的方法的流程圖。

其具體包括以下步驟：

s101：對原始后臺代碼執(zhí)行附加apidoc注釋的處理，得到附加apidoc注釋的后臺代碼；

本步驟的目的在于為原始的后臺代碼附加按照apidoc注釋標簽格式書寫的apidoc注釋，得到該附加apidoc注釋的后臺代碼。

其中，該apidoc注釋包括一些代碼段的必要信息，例如，api說明、參數(shù)說明、請求方式、請求示例以及返回示例等等。通過將這些代碼段所要表達的必要信息以注釋的形式書寫進原始后臺代碼，以使得到的附加該apidoc注釋的后臺代碼更便于被前端工程師所理解。

s102：對后臺代碼利用apidoc工具生成對應(yīng)的api文檔；

將經(jīng)過s101得到的附加該apidoc注釋的后臺代碼通過apidoc工具生成對應(yīng)的api文檔。其中，該apidoc工具是一個自動提取書寫進代碼段中的符合apidoc注釋格式的apidoc注釋的工具，且該apidoc注釋支持多種開發(fā)語言環(huán)境，例如，java、javascript、php、python、ruby、go等。該apidoc工具將注釋提取出來后會生成一個靜態(tài)的以html格式存在的api文檔。靜態(tài)的html格式api文檔文件具有在訪問該文件時無需再次聯(lián)網(wǎng)，是一個已經(jīng)保存在本地的完整的文件，并非是一個網(wǎng)頁鏈接，所以在發(fā)生緊急情況下或沒有聯(lián)網(wǎng)的情況下依然可以訪問。

s103：是否修改了后臺代碼；

本步驟是判斷是否發(fā)生了需要對s102使用的附加了apidoc注釋的后臺代碼進行修改，而會導(dǎo)致發(fā)生需要對代碼段進行修改的因素多種多樣，例如，app功能性的修改、發(fā)布平臺的各種要求以及修復(fù)各種小bug等等因素，此處并不限定是出于什么樣的因素需要進行對后臺代碼的修改，只要滿足對代碼段進行了修改這一結(jié)果即可。

s104：相應(yīng)的修改apidoc注釋，得到最新版后臺代碼；

一旦在s103出于各種因素對后臺代碼進行了修改，相應(yīng)的肯定要修改原來附加上的apidoc注釋，并書寫得到符合修改后的后臺代碼所對應(yīng)的新版apidoc注釋，最終得到附加了新版apidoc注釋的最新版后臺代碼。

s105：將最新版后臺代碼合并進git庫，并根據(jù)預(yù)設(shè)腳本調(diào)用預(yù)設(shè)命令生成最新版api文檔。

在得到s104中的最新版后臺代碼后，后臺工程師會將該最新版后臺代碼合進需要的代碼庫，此處的git庫是一種代碼管理庫，當(dāng)合進該git庫后，該git庫的服務(wù)器會根據(jù)預(yù)設(shè)腳本調(diào)用執(zhí)行一系列預(yù)設(shè)命令來生成最新版api文檔，得以及時、無遺漏的生成最新版api文檔。

其中預(yù)設(shè)腳本以及預(yù)設(shè)命令的表現(xiàn)形式多種多樣，此處并不限定具體為什么樣的腳本、什么樣的命令，只要該預(yù)設(shè)腳本以及預(yù)設(shè)命令能夠最終實現(xiàn)自動根據(jù)最新版后臺代碼來生成最新版api文檔即可，在實際情況中，可以根據(jù)開發(fā)廠商的不同、采用服務(wù)器型號的不同、操作習(xí)慣的不同等各種因素來綜合考慮作出相應(yīng)的差異化改變。

基于上述技術(shù)方案，本申請實施例提供的自動生成api文檔的方法，通過自動將后臺工程師修改后的最新版后臺代碼及時生成最新版api文檔，以使前端工程師能夠及時且不遺漏的得到最新的api文檔。因此，能夠以更加合理、更加及時的生成api文檔的方法來消除因重復(fù)修改出現(xiàn)的遺漏生成最新版api文檔的潛在隱患、提升后臺與前端工程師之間的工作效率。

下面請參見圖2，圖2為本申請實施例所提供的另一種自動生成api文檔的方法的流程圖。

本實施是針對上一實施例中的s105做出了具體的限定，其他步驟與上一實施例大體相同，詳細描寫內(nèi)容可以參見上一實施例中相關(guān)部分，在此不再贅述。

其具體包括以下步驟：

s201：當(dāng)最新版后臺代碼合并進git庫時，觸發(fā)shell腳本調(diào)用apidoc工具；

本步驟通過在該最新版后臺代碼合進該git庫時，觸發(fā)該git庫服務(wù)器的shell腳本，通過該shell腳本調(diào)用執(zhí)行內(nèi)置在該git庫服務(wù)器中的apidoc工具。

s202：通過apidoc工具生成最新版api文檔至指定的服務(wù)器路徑下；

通過s201步驟調(diào)用的該apidoc工具來將該最新版后臺代碼中書寫的新版apidoc注釋提取出來并生成靜態(tài)的以html格式存在的最新版api文檔，并將該api文檔置于指定的服務(wù)器路徑下。其中，將該該api文檔置于指定的服務(wù)器路徑下是出于多方面因素的考量，該服務(wù)器一定是該app開發(fā)商所擁有的，不管出于安全性因素的考慮還是傳輸方便的考慮，是至少需要在該服務(wù)器中存有相應(yīng)的備份文件的。

s203：shell腳本將最新版api文檔從服務(wù)器路徑下復(fù)制到用戶閱讀路徑下。

該shell腳本將從s202得到的且置于指定服務(wù)器路徑下的該最新版api文檔再次從指定服務(wù)器路徑下復(fù)制至前端工程師以及后臺工程師常用的文件路徑下，以便在服務(wù)器端進行過備份后，也便于前端以及后臺工程師的查看。

下面請參見圖3，圖3為本申請實施例所提供的又一種自動生成api文檔的方法的流程圖。

本實施例建立在一個具體的實際的應(yīng)用場景中，選擇了一個app開發(fā)商的實例，以及指令了生成的保存api文檔的服務(wù)器以及供工程進行閱讀的文檔路徑。

其具體包括以下步驟：

s301：在git庫的服務(wù)器上安裝node.js環(huán)境，并在聯(lián)網(wǎng)情況下安裝apidoc工具；

在后續(xù)所有步驟開始之前，需要保證在該git庫的服務(wù)器上安裝能夠運行該apidoc工具的環(huán)境，即，首先安裝node.js環(huán)境，接下來只需在聯(lián)網(wǎng)情況下安裝apidoc工具即可。

s302:對原始后臺代碼執(zhí)行附加apidoc注釋的處理，得到附加apidoc注釋的后臺代碼；

s303：對后臺代碼利用apidoc工具生成對應(yīng)的api文檔；

s304：對后臺代碼進行修改，相應(yīng)的修改apidoc注釋，得到最新版后臺代碼；

s305：當(dāng)最新版后臺代碼合并進git庫時，觸發(fā)shell腳本調(diào)用apidoc工具；

s306：生成最新版api文檔至公司1#開發(fā)服務(wù)器；

指定備份該最新版api文檔的為該開發(fā)廠商的1#git庫開發(fā)服務(wù)器。

s307：shell腳本將最新版api文檔從1#開發(fā)服務(wù)器復(fù)制到1#共享文件夾。

指定便于前端以及后臺工程師便于查看的路徑為1#共享文件夾。

基于上述技術(shù)方案，本申請實施例提供的自動生成api文檔的方法，通過在將后臺工程師修改后的最新版后臺代碼合進該git庫時，調(diào)用shell腳本執(zhí)行一系列指令并最終得到置于便于前端以及后臺工程師便于查看的路徑下的最新版api文檔，以使前端工程師能夠及時且不遺漏的得到最新的api文檔。因此，能夠以更加合理、更加及時的生成api文檔的方法來消除因重復(fù)修改出現(xiàn)的遺漏生成最新版api文檔的潛在隱患、提升后臺與前端工程師之間的工作效率。

上面提及的幾種方式，只是從實際出發(fā)提出的幾種具體例子，當(dāng)然可以有其他的方式來達到同樣的效果，此處并不做具體限定。

下面請參見圖4，圖4為本申請實施例所提供的一種自動生成api文檔的系統(tǒng)的結(jié)構(gòu)圖。

該系統(tǒng)可以包括：

添加注釋單元，用于對原始后臺代碼執(zhí)行附加apidoc注釋的處理，得到附加apidoc注釋的后臺代碼；其中，apidoc注釋為按照apidoc的注釋標簽格式書寫的；

第一生成單元，用于對后臺代碼利用apidoc工具生成對應(yīng)的api文檔；

修改單元，用于當(dāng)后臺代碼被修改時，相應(yīng)的修改apidoc注釋，得到最新版后臺代碼；

第二生成單元，用于將最新版后臺代碼合并進git庫，并根據(jù)預(yù)設(shè)腳本調(diào)用預(yù)設(shè)命令生成最新版api文檔。

進一步的，第二生成單元，包括：

腳本觸發(fā)子單元，用于當(dāng)最新版后臺代碼合并進git庫時，觸發(fā)shell腳本調(diào)用apidoc工具；

生成子單元，用于通過apidoc工具生成最新版api文檔至指定的服務(wù)器路徑下；

復(fù)制轉(zhuǎn)移子單元，用于shell腳本將最新版api文檔從服務(wù)器路徑下復(fù)制到用戶閱讀路徑下。

其中，生成子單元具體為：

利用apidoc工具生成靜態(tài)且為html格式的最新版api文檔至指定的服務(wù)器路徑下的子單元。

進一步，該系統(tǒng)還包括：

環(huán)境安裝單元，用于在git庫的服務(wù)器上安裝node.js環(huán)境，并在聯(lián)網(wǎng)情況下安裝apidoc工具。

下面為在添加注釋單元中進行一個實際的書寫例子，以java開發(fā)環(huán)境為例：

之后在第二生成單元中的生成子單元中使用命令apidoc–i–t–o，指定相應(yīng)的目錄即可生成相應(yīng)的最新版api文檔。

說明書中各個實施例采用遞進的方式描述，每個實施例重點說明的都是與其他實施例的不同之處，各個實施例之間相同相似部分互相參見即可。對于實施例公開的裝置而言，由于其與實施例公開的方法相對應(yīng)，所以描述的比較簡單，相關(guān)之處參見方法部分說明即可。

專業(yè)人員還可以進一步意識到，結(jié)合本文中所公開的實施例描述的各示例的單元及算法步驟，能夠以電子硬件、計算機軟件或者二者的結(jié)合來實現(xiàn)，為了清楚地說明硬件和軟件的可互換性，在上述說明中已經(jīng)按照功能一般性地描述了各示例的組成及步驟。這些功能究竟以硬件還是軟件方式來執(zhí)行，取決于技術(shù)方案的特定應(yīng)用和設(shè)計約束條件。專業(yè)技術(shù)人員可以對每個特定的應(yīng)用來使用不同方法來實現(xiàn)所描述的功能，但是這種實現(xiàn)不應(yīng)認為超出本申請的范圍。

以上對本申請所提供的自動生成api文檔的方法及系統(tǒng)進行了詳細介紹。本文中應(yīng)用了具體個例對本申請的原理及實施方式進行了闡述，以上實施例的說明只是用于幫助理解本申請的方法及其核心思想。應(yīng)當(dāng)指出，對于本技術(shù)領(lǐng)域的普通技術(shù)人員來說，在不脫離本申請原理的前提下，還可以對本申請進行若干改進和修飾，這些改進和修飾也落入本申請權(quán)利要求的保護范圍內(nèi)。

還需要說明的是，在本說明書中，諸如第一和第二等之類的關(guān)系術(shù)語僅僅用來將一個實體或者操作與另一個實體或操作區(qū)分開來，而不一定要求或者暗示這些實體或操作之間存在任何這種實際的關(guān)系或者順序。而且，術(shù)語“包括”、“包含”或者其任何其他變體意在涵蓋非排他性的包含，從而使得包括一系列要素的過程、方法、物品或者設(shè)備不僅包括那些要素，而且還包括沒有明確列出的其他要素，或者是還包括為這種過程、方法、物品或者設(shè)備所固有的要素。在沒有更多限制的情況下，由語句“包括一個……”限定的要素，并不排除在包括所述要素的過程、方法、物品或者設(shè)備中還存在另外的相同要素。