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

你們好，我是小富~

前幾天粉絲羣有小夥伴問，有啥好用的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"
}

看到在showdoc對應的項目裏已經建立了名字爲xiaofu的文檔。

說兩句

前邊說過showdoc現有的功能postman基本都支持，但postman功能過於繁雜不夠簡潔，加上網絡條件等諸多限制，協同辦公的效率並不高，而Runapi配合showdoc在某些場景下可以很大程度上提高咱們開發交付的效率，因此能自動生成的絕對不手寫！

再怎麼BB吹噓都是蒼白的，好很差用，適不適合本身，動手搞一下一目瞭然

我是小富，下期見~

整理了幾百本各種技術電子書，有須要的同窗自取。技術羣快滿了，想進的同窗能夠加我好友，和大佬們一塊兒吹吹技術。

電子書地址