摘要:仿照此種寫(xiě)法,在你的項(xiàng)目中插入類(lèi)似的注釋?zhuān)材苓_(dá)到自動(dòng)生成文檔的效果。執(zhí)行以下命令,腳本會(huì)自動(dòng)遞歸掃描本目錄和子目錄的所有文本代碼文件,并生成文檔。如果是,程序會(huì)自動(dòng)進(jìn)行格式化展示。
介紹
showdoc是一個(gè)適合IT團(tuán)隊(duì)的文檔工具,閱讀本文前需要對(duì)showdoc有基本了解 。基本介紹可看:https://www.showdoc.cc/help
對(duì)于寫(xiě)API文檔這件事,雖然說(shuō)文本編輯軟件或者接口管理軟件能在某種程度上提高我們的效率,但我們依然可以試圖借助技術(shù)的力量,更自動(dòng)化地生成API文檔,釋放自己的生產(chǎn)力。
為此,showdoc官方提供了一種自動(dòng)化解決方案。在代碼里編寫(xiě)特定格式的程序注釋?zhuān)缓髎howdoc通過(guò)讀取這些注釋來(lái)自動(dòng)生成文檔。由于這種方式不跟特定的語(yǔ)言耦合,因此它的使用范圍相當(dāng)廣泛,可用支持c++、java、php、node、python等等常見(jiàn)的主流語(yǔ)言。
采用這種方式,盡管我們?cè)诘谝淮翁顚?xiě)注釋的時(shí)候可能會(huì)有些繁瑣,但是它后期帶來(lái)的可維護(hù)性是非常高的。代碼變動(dòng)后,不需要再額外登錄showdoc,直接在代碼里修改注釋即可。同時(shí)自動(dòng)化的腳本也可以加入持續(xù)集成或者某些自動(dòng)化工程里,讓“寫(xiě)API文檔”這件事如"單元測(cè)試"般納入工程工作流里面。
windows無(wú)法直接運(yùn)行sh腳本,需要額外下載軟件。
推薦下載git for windows:https://git-scm.com/download/win 下載后直接雙擊安裝即可。
如果從官網(wǎng)下載比較慢,可用考慮下載由第三方開(kāi)發(fā)者維護(hù)的國(guó)內(nèi)版(showdoc官方不保證其長(zhǎng)期穩(wěn)定):
https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe
以上軟件是基礎(chǔ)環(huán)境。安裝好了后,還需要下載showdoc官方腳本:https://www.showdoc.cc/script/showdoc_api.sh
下載后,將showdoc_api.sh放在你的項(xiàng)目目錄下。右擊,選擇編輯。
腳本內(nèi)容的前面有兩個(gè)變量,api_key 和 api_token ,這個(gè)需要用戶(hù)自行填寫(xiě)。關(guān)于這兩個(gè)變量的取值,請(qǐng)登錄showdoc,進(jìn)入某個(gè)項(xiàng)目的設(shè)置,點(diǎn)擊開(kāi)放API,便可以看到說(shuō)明。showdoc_api.sh生成的文檔會(huì)放進(jìn)你填寫(xiě)的這個(gè)項(xiàng)目里。除了api_key 和 api_token ,還有一個(gè)url變量。如果是使用www.showdoc.cc ,則不需要修改。如果是使用開(kāi)源版showdoc,則需要將地址改為http://xx.com/server/?s=/api/open/fromComments 其中,別忘記了url里含server目錄。
填寫(xiě)完畢,保存。然后直接雙擊運(yùn)行,腳本會(huì)自動(dòng)遞歸掃描本目錄和子目錄的所有文本代碼文件,并生成API文檔。
為了方便測(cè)試,官方還提供了一個(gè)例子。請(qǐng)下載:
https://www.showdoc.cc/script/api_demo.test
下載后,把a(bǔ)pi_demo.test文件放在showdoc_api.sh所在的目錄或者子目錄下。運(yùn)行的時(shí)候它便會(huì)生成文檔到你指定的項(xiàng)目地址中。
如果你想?yún)⒖脊俜絛emo是怎么寫(xiě)的,可用鼠標(biāo)右擊api_demo.test,選擇編輯。仿照此種寫(xiě)法,在你的項(xiàng)目中插入類(lèi)似的注釋?zhuān)材苓_(dá)到自動(dòng)生成文檔的效果。詳細(xì)語(yǔ)法會(huì)在文章后面部分說(shuō)明。
如果你想應(yīng)用到其他項(xiàng)目,可以把showdoc_api.sh復(fù)制一份到其他項(xiàng)目中。使用方法和前面一樣。
Linux/Mac下使用指引先cd進(jìn)入你的項(xiàng)目目錄,命令行模式下輸入:
wget https://www.showdoc.cc/script/showdoc_api.sh
下載完畢,編輯
vi showdoc_api.sh
腳本內(nèi)容的前面有兩個(gè)變量,api_key 和 api_token ,這個(gè)需要用戶(hù)自行填寫(xiě)。關(guān)于這兩個(gè)變量的取值,請(qǐng)登錄showdoc,進(jìn)入某個(gè)項(xiàng)目的設(shè)置,點(diǎn)擊開(kāi)放API,便可以看到說(shuō)明。showdoc_api.sh生成的文檔會(huì)放進(jìn)你填寫(xiě)的這個(gè)項(xiàng)目里。除了api_key 和 api_token ,還有一個(gè)url變量。如果是使用 www.showdoc.cc ,則不需要修改。如果是使用開(kāi)源版showdoc,則需要將地址改為http://xx.com/server/?s=/api/... ,其中,別忘記了url里含server目錄。
保存文件后。執(zhí)行以下命令,腳本會(huì)自動(dòng)遞歸掃描本目錄和子目錄的所有文本代碼文件,并生成API文檔。
chmod +x showdoc_api.sh ./showdoc_api.sh
為了方便測(cè)試,官方還提供了一個(gè)例子。請(qǐng)下載:
wget https://www.showdoc.cc/script/api_demo.test
下載后,把a(bǔ)pi_demo.test文件放在showdoc_api.sh所在的目錄或者子目錄下。運(yùn)行的時(shí)候它便會(huì)生成文檔到你指定的項(xiàng)目地址中。
如果你想?yún)⒖脊俜絛emo是怎么寫(xiě)的,可用vi命令打開(kāi)api_demo.test。仿照此種寫(xiě)法,在你的項(xiàng)目中插入類(lèi)似的注釋?zhuān)材苓_(dá)到自動(dòng)生成文檔的效果。詳細(xì)語(yǔ)法會(huì)在文章后面部分說(shuō)明。
如果你還想應(yīng)用到其他項(xiàng)目,可以把showdoc_api.sh復(fù)制一份到其他項(xiàng)目中。使用方法和前面一樣。
或者不轉(zhuǎn)移位置,直接通過(guò)參數(shù)指定掃描目錄。如
./showdoc_api.sh /myapp/demo/
語(yǔ)法說(shuō)明一個(gè)標(biāo)準(zhǔn)語(yǔ)法例子:
/** * showdoc * @catalog 測(cè)試文檔/用戶(hù)相關(guān) * @title 用戶(hù)登錄 * @description 用戶(hù)登錄的接口 * @method get * @url https://www.showdoc.cc/home/user/login * @param username 必選 string 用戶(hù)名 * @param password 必選 string 密碼 * @param name 可選 string 用戶(hù)昵稱(chēng) * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吳系掛","groupid":2,"reg_time":"1436864169","last_login_time":"0"}} * @return_param groupid int 用戶(hù)組id * @return_param name string 用戶(hù)昵稱(chēng) * @remark 這里是備注信息 * @number 99 */
語(yǔ)法說(shuō)明
@catalog // 生成文檔要放到哪個(gè)目錄。如果只是二級(jí)目錄,則直接寫(xiě)目錄名字。如果是三級(jí)目錄,而需要寫(xiě)二級(jí)目錄/三級(jí)目錄,即用 / 隔開(kāi)。 @title //表示生成的文檔標(biāo)題 @description // 是文檔內(nèi)容中對(duì)接口的描述信息 @method //接口請(qǐng)求方式。一般是get或者post @url //接口URL @param //參數(shù)表格說(shuō)明。一行注釋對(duì)應(yīng)著表格的一行。用空格或者tab符號(hào)來(lái)隔開(kāi)每一列信息。 @return //返回內(nèi)容。請(qǐng)把返回內(nèi)容壓縮在同一行內(nèi)。如果是json,程序會(huì)自動(dòng)進(jìn)行格式化展示。 如果是非json內(nèi)容,則原樣展示。 @return_param //返回參數(shù)的表格說(shuō)明。一行注釋對(duì)應(yīng)著表格的一行。用空格或者tab符號(hào)來(lái)隔開(kāi)每一列信息。 @remark //備注信息 @number //可選。文檔的序號(hào)。其他信息
請(qǐng)嚴(yán)格按照我們的語(yǔ)法來(lái)填寫(xiě)程序注釋。如果格式不對(duì),則可能引發(fā)未知的解析錯(cuò)誤。
出于數(shù)據(jù)安全考慮,showdoc不允許直接通過(guò)代碼刪除文檔。只能新增或者修改。所以,如果你要?jiǎng)h除文檔,請(qǐng)登錄showdoc網(wǎng)頁(yè)端完成。
本腳本只能通過(guò)特定的程序注釋來(lái)生成文檔,使用范圍有限。如果你是想通過(guò)其他方式自由地生成文檔,如通過(guò)word、通過(guò)博客軟件等,請(qǐng)參考我們更自由的開(kāi)放API:https://www.showdoc.cc/page/1...
如果你的項(xiàng)目下太多文件,則可能導(dǎo)致腳本掃描很慢。推薦把腳本放到需要生成注釋的那個(gè)目錄里。一般來(lái)講,一個(gè)項(xiàng)目不會(huì)所有目錄都需要生成文檔的
文章版權(quán)歸作者所有,未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為,您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請(qǐng)注明本文地址:http://specialneedsforspecialkids.com/yun/29273.html
摘要:仿照此種寫(xiě)法,在你的項(xiàng)目中插入類(lèi)似的注釋?zhuān)材苓_(dá)到自動(dòng)生成文檔的效果。執(zhí)行以下命令,腳本會(huì)自動(dòng)遞歸掃描本目錄和子目錄的所有文本代碼文件,并生成文檔。如果是,程序會(huì)自動(dòng)進(jìn)行格式化展示。 介紹 showdoc是一個(gè)適合IT團(tuán)隊(duì)的文檔工具,閱讀本文前需要對(duì)showdoc有基本了解 。基本介紹可看:https://www.showdoc.cc/help 對(duì)于寫(xiě)API文檔這件事,雖然說(shuō)文本編輯...
摘要:關(guān)于的詳細(xì)介紹,可看好的數(shù)據(jù)字典文檔能夠清晰地反映出數(shù)據(jù)庫(kù)的結(jié)構(gòu)以及相關(guān)釋義,方便技術(shù)人員查閱。自動(dòng)執(zhí)行的情況下,只會(huì)自動(dòng)新增和修改文檔,不會(huì)自動(dòng)刪除文檔主要出于數(shù)據(jù)安全考慮。 介紹 showdoc是一個(gè)非常適合IT團(tuán)隊(duì)的在線(xiàn)API文檔、技術(shù)文檔工具。你可以使用Showdoc來(lái)編寫(xiě)在線(xiàn)API文檔、技術(shù)文檔、數(shù)據(jù)字典、在線(xiàn)手冊(cè)。關(guān)于showdoc的詳細(xì)介紹,可看:https://www....
摘要:關(guān)于的詳細(xì)介紹,可看好的數(shù)據(jù)字典文檔能夠清晰地反映出數(shù)據(jù)庫(kù)的結(jié)構(gòu)以及相關(guān)釋義,方便技術(shù)人員查閱。自動(dòng)執(zhí)行的情況下,只會(huì)自動(dòng)新增和修改文檔,不會(huì)自動(dòng)刪除文檔主要出于數(shù)據(jù)安全考慮。 介紹 showdoc是一個(gè)非常適合IT團(tuán)隊(duì)的在線(xiàn)API文檔、技術(shù)文檔工具。你可以使用Showdoc來(lái)編寫(xiě)在線(xiàn)API文檔、技術(shù)文檔、數(shù)據(jù)字典、在線(xiàn)手冊(cè)。關(guān)于showdoc的詳細(xì)介紹,可看:https://www....
閱讀 2845·2021-10-21 09:38
閱讀 2751·2021-10-11 10:59
閱讀 3022·2021-09-27 13:36
閱讀 1649·2021-08-23 09:43
閱讀 790·2019-08-29 14:14
閱讀 3034·2019-08-29 12:13
閱讀 3203·2019-08-29 12:13
閱讀 310·2019-08-26 12:24