前幾天有小夥伴問,有啥好用的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/AAA
可以複製現有的項目,或直接導入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格式的文檔。
比如我們新建個項目“AAA
”,分別建三個接口“點在
”、“在看
”、“關注
”,緊接着快速生成參數和響應結果數據並保存。
點擊右上角的文檔鏈接
設置訪問密碼,不填默認是公開的,複製文檔鏈接在瀏覽器中打開,看到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吹噓都是蒼白的,好不好用,適不適合自己,動手搞一下一目瞭然
最近有很多人問,有沒有讀者交流羣,想知道怎麼加入。
最近我創建了一些羣,大家可以加入。交流羣都是免費的,只需要大家加入之後不要隨便發廣告,多多交流技術就好了。
目前創建了多個交流羣,全國交流羣、北上廣杭深等各地區交流羣、面試交流羣、資源共享羣等。
有興趣入羣的同學,可長按掃描下方二維碼,一定要備註:全國 Or 城市 Or 面試 Or 資源,根據格式備註,可更快被通過且邀請進羣。
往期推薦
程序員千萬不要做舔狗啊!
官方認證:軟件及信息技術從業者爲新生代農民工
關於解決併發問題,99%的程序員都會忽略的一個重要方案!
本文分享自微信公衆號 - Hollis(hollischuang)。
如有侵權,請聯繫 [email protected] 刪除。
本文參與“OSC源創計劃”,歡迎正在閱讀的你也加入,一起分享。