干掉 Postman？測(cè)試接口直接生成API文檔，這個(gè)工具我愛(ài)了
大家好，我是小富~
前幾天粉絲群有小伙伴問(wèn)，有啥好用的API文檔工具推薦，無(wú)意間發(fā)現(xiàn)了一款工具，這里馬不停蹄的來(lái)給大家分享一下。
ShowDoc一個(gè)非常適合團(tuán)隊(duì)的在線API文檔工具，也支持用docker自建文檔服務(wù)，不過(guò)為了方便演示，我直接用了平臺(tái)在線服務(wù)。官網(wǎng)地址：
https://www.showdoc.com.cn/item/index
可以使用markdown語(yǔ)法來(lái)寫API文檔、數(shù)據(jù)字典文檔、技術(shù)文檔、在線excel文檔。但像我這種資深的懶人程序員，其實(shí)更看重的是showdoc的自動(dòng)化生成文檔的特性，它可以從代碼注釋中自動(dòng)生成API文檔，或者搭配RunApi客戶端（類似postman的api調(diào)試工具）一邊調(diào)試接口、一邊自動(dòng)生成文檔。
下邊從頭演示下，來(lái)瞅瞅這玩意好用在哪？
初識(shí) ShowDoc
ShowDoc新建項(xiàng)目可選常規(guī)的API文檔、在線表格、或者單頁(yè)文檔（不支持目錄分層），允許對(duì)項(xiàng)目文檔設(shè)置訪問(wèn)密碼，自定義域名，這里并不是真正意義上的“域名”，只是在文檔服務(wù)域名后加了一級(jí)目錄，例如：
www.showdoc.com.cn/程序員內(nèi)點(diǎn)事
可以復(fù)制現(xiàn)有的項(xiàng)目，或直接導(dǎo)入Postman、swagger的API接口配置Json文件。提供的開放API是自動(dòng)化生成文檔的關(guān)鍵，先記住有api_key、api_token這兩個(gè)屬性，后邊詳細(xì)講。
進(jìn)入項(xiàng)目后點(diǎn)擊右上角 + 編輯文檔，ShowDoc預(yù)置了幾種文檔模板，也可以把自定義的文檔存為模板；支持在線Mock服務(wù)，提前定義好接口的數(shù)據(jù)格式，先提供在線臨時(shí)接口，這樣就可以和前端同步開發(fā)，后邊無(wú)縫切換；還有個(gè)簡(jiǎn)單的API在線測(cè)試功能。
在線表格樣式很簡(jiǎn)潔
導(dǎo)出文檔有word、Markdown兩種格式。
支持版本控制，能看到每次修改的記錄，回滾任意一個(gè)版本的修改。
在向別人分享在線文檔時(shí)，如果不想將整個(gè)API目錄都暴漏，可以選擇進(jìn)行單頁(yè)面分享。
看到這感覺(jué)showdoc很普通啊，好像沒(méi)什么特別的地方，上邊的這些文檔都是需要我們手動(dòng)書寫的，比較繁瑣不推薦這么搞，接下來(lái)咱們看看如何自動(dòng)化生成文檔。
自動(dòng)生成文檔
showdoc有三種自動(dòng)生成API文檔的方式：
使用Runapi工具自動(dòng)生成（推薦） 使用程序代碼注釋自動(dòng)生成 自動(dòng)生成數(shù)據(jù)字典 自己寫程序調(diào)用接口來(lái)生成
Runapi工具
Runapi是一個(gè)以接口為核心的開發(fā)測(cè)試工具（可以看做是Postman的精簡(jiǎn)版）。目前客戶端支持win、mac、linux平臺(tái)和在線版 ，包含接口測(cè)試、自動(dòng)流程測(cè)試、Mock數(shù)據(jù)、項(xiàng)目協(xié)作等功能。
單純的Runapi和Postman相比優(yōu)勢(shì)并不大，而與showdoc配合使用效率比較顯著，用runapi測(cè)試接口的同時(shí)它將自動(dòng)生成API文檔到showdoc，也可共用showdoc的團(tuán)隊(duì)管理機(jī)制實(shí)現(xiàn)多人協(xié)作。
Runapi客戶端可以創(chuàng)建帶調(diào)試的API接口文檔、或者M(jìn)arkdown格式的文檔。
比如我們新建個(gè)項(xiàng)目“程序員內(nèi)點(diǎn)事”，分別建三個(gè)接口“點(diǎn)在”、“在看”、“關(guān)注”，緊接著快速生成參數(shù)和響應(yīng)結(jié)果數(shù)據(jù)并保存。
點(diǎn)擊右上角的文檔鏈接設(shè)置訪問(wèn)密碼，不填默認(rèn)是公開的，復(fù)制文檔鏈接在瀏覽器中打開，看到API接口文檔已經(jīng)生成。runapi還有全局參數(shù)、環(huán)境隔離。其實(shí)Postman也支持這樣的功能，不過(guò)畢竟不是國(guó)內(nèi)產(chǎn)品，網(wǎng)絡(luò)訪問(wèn)等方面很受限制。
還有一個(gè)比較好的地方，Runapi支持接口執(zhí)行前后的腳本，比如響應(yīng)數(shù)據(jù)的斷言測(cè)試，彈框顯示都挺好用的。
代碼注釋
把接口的信息寫在注釋里也可以自動(dòng)生成文檔到showdoc，但這種我并不太喜歡，主要是侵入性比較強(qiáng)，讓代碼的閱讀性變的比較差，一坨坨看著很不爽。
?/**
?*?showdoc
?*?@catalog?測(cè)試文檔/用戶相關(guān)
?*?@title?用戶注冊(cè)
?*?@description?用戶注冊(cè)的接口
?*?@method?post
?*?@url?https://www.showdoc.com.cn/home/user/login
?*?@param?username?必選?string?用戶名??
?*?@param?password?必選?string?密碼??
?*?@param?name?可選?string?用戶昵稱??
?*?@return?{"error_code":0,"data":{"uid":"1","username":"12154545","name":"吳系掛","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
?*?@return_param?groupid?int?用戶組id
?*?@return_param?name?string?用戶昵稱
?*?@remark?這里是備注信息
?*?@number?99
?*/
?public?Object?register(){
這種方式的實(shí)現(xiàn)也比較簡(jiǎn)單，還記得前邊的提到的api_key、api_token這兩個(gè)屬性嘛，現(xiàn)在派上用場(chǎng)了，下邊我用windows環(huán)境演示。
首先本地要有g(shù)it環(huán)境：
https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe
再下載showdoc官方提供的腳本
https://www.showdoc.cc/script/showdoc_api.sh
修改showdoc_api.sh，替換我們api_key和api_token變量值，URL如果沒(méi)搭建自己的文檔服務(wù)不用改。
將showdoc_api.sh放在你的項(xiàng)目目錄下，直接雙擊運(yùn)行，腳本會(huì)自動(dòng)遞歸掃描本目錄和子目錄的所有文本代碼文件，并生成API文檔。
showdoc_api.sh生成的文檔會(huì)放進(jìn)你填寫api_token的這個(gè)項(xiàng)目里。
生成數(shù)據(jù)字典
如果我們想直接從數(shù)據(jù)庫(kù)字典表生成數(shù)據(jù)字典文檔，showdoc也是支持的，先下載官方提供的腳本
wget?https://www.showdoc.cc/script/showdoc_db.sh
修改腳本里的配置，數(shù)據(jù)庫(kù)、api_key、api_token等信息，直接執(zhí)行后數(shù)據(jù)庫(kù)表結(jié)構(gòu)信息同步到showdoc。
如下配置的變量名和解釋
效果就是如下圖這樣，生成了數(shù)據(jù)表字典文檔，在一些特定場(chǎng)景下還是很方便的。
開放API
showdoc開放了文檔編輯的API，我們可以在代碼中調(diào)用API創(chuàng)建、編輯文檔。這樣使用的場(chǎng)景就比較靈活了。
https://www.showdoc.cc/server/api/item/updateByApi
API參數(shù)如下，文檔內(nèi)容，可傳遞markdown格式的文本或者h(yuǎn)tml源碼都可以。
測(cè)試一下接口組裝必要的參數(shù)，用簡(jiǎn)易在線API調(diào)試工具發(fā)送
{
??"api_key":?"8e52cbad736aa9832b92acc4b34a830e961861279",
??"api_token":?"9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
??"page_title":?"xiaofu",
??"page_content":?"nihao"
}
看到在showdoc對(duì)應(yīng)的項(xiàng)目里已經(jīng)創(chuàng)建了名字為xiaofu的文檔。
說(shuō)兩句
前邊說(shuō)過(guò)showdoc現(xiàn)有的功能postman基本都支持，但postman功能過(guò)于繁雜不夠簡(jiǎn)潔，加上網(wǎng)絡(luò)條件等諸多限制，協(xié)同辦公的效率并不高，而Runapi配合showdoc在某些場(chǎng)景下能夠很大程度上提升我們開發(fā)交付的效率，所以能自動(dòng)生成的絕對(duì)不手寫！
再怎么BB吹噓都是蒼白的，好不好用，適不適合自己，動(dòng)手搞一下一目了然
SpringBoot三大開發(fā)工具，你都用過(guò)么？
Java 18 都要來(lái)了，你不會(huì)還在用Java 8吧？
面試官：有了 for 循環(huán) 為什么還要 forEach ？
關(guān)注公眾號(hào)【Java技術(shù)江湖】后回復(fù)“PDF”即可領(lǐng)取200+頁(yè)的《Java工程師面試指南》
強(qiáng)烈推薦，幾乎涵蓋所有Java工程師必知必會(huì)的知識(shí)點(diǎn)，不管是復(fù)習(xí)還是面試，都很實(shí)用。
