幹掉 Postman？測試介面直接生成API文件，這個工具賊好用

程式設計師小富發表於2021-07-16

本文案例收錄在 github.com/chengxy-nds/Springboot-...

大家好，我是小富~

前幾天粉絲群有小夥伴問，有啥好用的API文件工具推薦，無意間發現了一款工具，這裡馬不停蹄的來給大家分享一下。

ShowDoc一個非常適合團隊的線上API文件工具，也支援用docker自建文件服務，不過為了方便演示，我直接用了平臺線上服務。官網地址：

https://www.showdoc.com.cn/item/index

可以使用markdown語法來寫API文件、資料字典文件、技術文件、線上excel文件。但像我這種資深的懶人程式設計師，其實更看重的是showdoc的自動化生成文件的特性，它可以從程式碼註釋中自動生成API文件，或者搭配RunApi客戶端（類似postman的api除錯工具）一邊除錯介面、一邊自動生成文件。

下邊從頭演示下，來瞅瞅這玩意好用在哪？

初識 ShowDoc

ShowDoc新建專案可選常規的API文件、線上表格、或者單頁文件（不支援目錄分層），允許對專案文件設定訪問密碼，自定義域名，這裡並不是真正意義上的“域名”，只是在文件服務域名後加了一級目錄，例如：

www.showdoc.com.cn/程式設計師內點事

可以複製現有的專案，或直接匯入Postman、swagger的API介面配置Json檔案。提供的開放API是自動化生成文件的關鍵，先記住有api_key、api_token這兩個屬性，後邊詳細講。

進入專案後點選右上角 + 編輯文件，ShowDoc預置了幾種文件模板，也可以把自定義的文件存為模板；支援線上Mock服務，提前定義好介面的資料格式，先提供線上臨時介面，這樣就可以和前端同步開發，後邊無縫切換；還有個簡單的API線上測試功能。

線上表格樣式很簡潔

匯出文件有word、Markdown兩種格式。

支援版本控制，能看到每次修改的記錄，回滾任意一個版本的修改。

在向別人分享線上文件時，如果不想將整個API目錄都暴漏，可以選擇進行單頁面分享。

看到這感覺showdoc很普通啊，好像沒什麼特別的地方，上邊的這些文件都是需要我們手動書寫的，比較繁瑣不推薦這麼搞，接下來我們們看看如何自動化生成文件。

自動生成文件

showdoc有三種自動生成API文件的方式：

使用Runapi工具自動生成（推薦）
使用程式程式碼註釋自動生成
自動生成資料字典
自己寫程式呼叫介面來生成

Runapi工具

Runapi是一個以介面為核心的開發測試工具（可以看做是Postman的精簡版）。目前客戶端支援win、mac、linux平臺和線上版，包含介面測試、自動流程測試、Mock資料、專案協作等功能。

單純的Runapi和Postman相比優勢並不大，而與showdoc配合使用效率比較顯著，用runapi測試介面的同時它將自動生成API文件到showdoc，也可共用showdoc的團隊管理機制實現多人協作。

Runapi客戶端可以建立帶除錯的API介面文件、或者Markdown格式的文件。

比如我們新建個專案“程式設計師內點事”，分別建三個介面“點在”、“在看”、“關注”，緊接著快速生成引數和響應結果資料並儲存。

點選右上角的文件連結設定訪問密碼，不填預設是公開的，複製文件連結在瀏覽器中開啟，看到API介面文件已經生成。runapi還有全域性引數、環境隔離。其實Postman也支援這樣的功能，不過畢竟不是國內產品，網路訪問等方面很受限制。

還有一個比較好的地方，Runapi支援介面執行前後的指令碼，比如響應資料的斷言測試，彈框顯示都挺好用的。

程式碼註釋

把介面的資訊寫在註釋裡也可以自動生成文件到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(){

這種方式的實現也比較簡單，還記得前邊的提到的api_key、api_token這兩個屬性嘛，現在派上用場了，下邊我用windows環境演示。

首先本地要有git環境：

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的這個專案裡。

生成資料字典

如果我們想直接從資料庫字典表生成資料字典文件，showdoc也是支援的，先下載官方提供的指令碼

wget https://www.showdoc.cc/script/showdoc_db.sh

修改指令碼里的配置，資料庫、api_key、api_token等資訊，直接執行後資料庫表結構資訊同步到showdoc。

如下配置的變數名和解釋

效果就是如下圖這樣，生成了資料表字典文件，在一些特定場景下還是很方便的。

開放API

showdoc開放了文件編輯的API，我們可以在程式碼中呼叫API建立、編輯文件。這樣使用的場景就比較靈活了。

https://www.showdoc.cc/server/api/item/updateByApi

API引數如下，文件內容，可傳遞markdown格式的文字或者html原始碼都可以。

測試一下介面組裝必要的引數，用簡易線上API除錯工具傳送

{
  "api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
  "api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
  "page_title": "xiaofu",
  "page_content": "nihao"
}