干掉 Postman？測試接口直接生成API文檔，這個工具我愛了
前幾天有小伙伴問，有啥好用的API文檔工具推薦，無意間發(fā)現(xiàn)了一款工具，這里馬不停蹄的來給大家分享一下。
ShowDoc一個非常適合團隊的在線API文檔工具，也支持用docker自建文檔服務，不過為了方便演示，我直接用了平臺在線服務。官網(wǎng)地址：
https://www.showdoc.com.cn/item/index
可以使用markdown語法來寫API文檔、數(shù)據(jù)字典文檔、技術文檔、在線excel文檔。但像我這種資深的懶人程序員，其實更看重的是showdoc的自動化生成文檔的特性，它可以從代碼注釋中自動生成API文檔，或者搭配RunApi客戶端（類似postman的api調試工具）一邊調試接口、一邊自動生成文檔。
下邊從頭演示下，來瞅瞅這玩意好用在哪？
初識 ShowDoc
ShowDoc新建項目可選常規(guī)的API文檔、在線表格、或者單頁文檔（不支持目錄分層），允許對項目文檔設置訪問密碼，自定義域名，這里并不是真正意義上的“域名”，只是在文檔服務域名后加了一級目錄，例如：
www.showdoc.com.cn/AAA
可以復制現(xiàn)有的項目，或直接導入Postman、swagger的API接口配置Json文件。提供的開放API是自動化生成文檔的關鍵，先記住有api_key、api_token這兩個屬性，后邊詳細講。
進入項目后點擊右上角 + 編輯文檔，ShowDoc預置了幾種文檔模板，也可以把自定義的文檔存為模板；支持在線Mock服務，提前定義好接口的數(shù)據(jù)格式，先提供在線臨時接口，這樣就可以和前端同步開發(fā)，后邊無縫切換；還有個簡單的API在線測試功能。
在線表格樣式很簡潔
導出文檔有word、Markdown兩種格式。
支持版本控制，能看到每次修改的記錄，回滾任意一個版本的修改。
在向別人分享在線文檔時，如果不想將整個API目錄都暴漏，可以選擇進行單頁面分享。
看到這感覺showdoc很普通啊，好像沒什么特別的地方，上邊的這些文檔都是需要我們手動書寫的，比較繁瑣不推薦這么搞，接下來咱們看看如何自動化生成文檔。
自動生成文檔
showdoc有三種自動生成API文檔的方式：
使用Runapi工具自動生成（推薦）
使用程序代碼注釋自動生成
自動生成數(shù)據(jù)字典
自己寫程序調用接口來生成
Runapi工具
Runapi是一個以接口為核心的開發(fā)測試工具（可以看做是Postman的精簡版）。目前客戶端支持win、mac、linux平臺和在線版 ，包含接口測試、自動流程測試、Mock數(shù)據(jù)、項目協(xié)作等功能。
單純的Runapi和Postman相比優(yōu)勢并不大，而與showdoc配合使用效率比較顯著，用runapi測試接口的同時它將自動生成API文檔到showdoc，也可共用showdoc的團隊管理機制實現(xiàn)多人協(xié)作。
Runapi客戶端可以創(chuàng)建帶調試的API接口文檔、或者Markdown格式的文檔。
比如我們新建個項目“AAA”，分別建三個接口“點在”、“在看”、“關注”，緊接著快速生成參數(shù)和響應結果數(shù)據(jù)并保存。
點擊右上角的文檔鏈接設置訪問密碼，不填默認是公開的，復制文檔鏈接在瀏覽器中打開，看到API接口文檔已經(jīng)生成。runapi還有全局參數(shù)、環(huán)境隔離。其實Postman也支持這樣的功能，不過畢竟不是國內產品，網(wǎng)絡訪問等方面很受限制。
還有一個比較好的地方，Runapi支持接口執(zhí)行前后的腳本，比如響應數(shù)據(jù)的斷言測試，彈框顯示都挺好用的。
代碼注釋
把接口的信息寫在注釋里也可以自動生成文檔到showdoc，但這種我并不太喜歡，主要是侵入性比較強，讓代碼的閱讀性變的比較差，一坨坨看著很不爽。
/**
* showdoc
* @catalog 測試文檔/用戶相關
* @title 用戶注冊
* @description 用戶注冊的接口
* @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(){
這種方式的實現(xiàn)也比較簡單，還記得前邊的提到的api_key、api_token這兩個屬性嘛，現(xiàn)在派上用場了，下邊我用windows環(huán)境演示。
首先本地要有git環(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如果沒搭建自己的文檔服務不用改。
將showdoc_api.sh放在你的項目目錄下，直接雙擊運行，腳本會自動遞歸掃描本目錄和子目錄的所有文本代碼文件，并生成API文檔。
showdoc_api.sh生成的文檔會放進你填寫api_token的這個項目里。
生成數(shù)據(jù)字典
如果我們想直接從數(shù)據(jù)庫字典表生成數(shù)據(jù)字典文檔，showdoc也是支持的，先下載官方提供的腳本
wget https://www.showdoc.cc/script/showdoc_db.sh
修改腳本里的配置，數(shù)據(jù)庫、api_key、api_token等信息，直接執(zhí)行后數(shù)據(jù)庫表結構信息同步到showdoc。
如下配置的變量名和解釋
效果就是如下圖這樣，生成了數(shù)據(jù)表字典文檔，在一些特定場景下還是很方便的。
開放API
showdoc開放了文檔編輯的API，我們可以在代碼中調用API創(chuàng)建、編輯文檔。這樣使用的場景就比較靈活了。
https://www.showdoc.cc/server/api/item/updateByApi
API參數(shù)如下，文檔內容，可傳遞markdown格式的文本或者html源碼都可以。
測試一下接口組裝必要的參數(shù)，用簡易在線API調試工具發(fā)送
{
"api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
"api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
"page_title": "xiaofu",
"page_content": "nihao"
}
看到在showdoc對應的項目里已經(jīng)創(chuàng)建了名字為xiaofu的文檔。
說兩句
前邊說過showdoc現(xiàn)有的功能postman基本都支持，但postman功能過于繁雜不夠簡潔，加上網(wǎng)絡條件等諸多限制，協(xié)同辦公的效率并不高，而Runapi配合showdoc在某些場景下能夠很大程度上提升我們開發(fā)交付的效率，所以能自動生成的絕對不手寫！
再怎么BB吹噓都是蒼白的，好不好用，適不適合自己，動手搞一下一目了然
技術交流群最近有很多人問，有沒有讀者交流群，想知道怎么加入。
最近我創(chuàng)建了一些群，大家可以加入。交流群都是免費的，只需要大家加入之后不要隨便發(fā)廣告，多多交流技術就好了。
目前創(chuàng)建了多個交流群，全國交流群、北上廣杭深等各地區(qū)交流群、面試交流群、資源共享群等。
有興趣入群的同學，可長按掃描下方二維碼，一定要備注：全國 Or 城市 Or 面試 Or 資源，根據(jù)格式備注，可更快被通過且邀請進群。
往期推薦
程序員千萬不要做舔狗啊！
官方認證：軟件及信息技術從業(yè)者為新生代農民工
關于解決并發(fā)問題，99%的程序員都會忽略的一個重要方案！