|
源 / 文/ ShowDoc一個(gè)非常適合團(tuán)隊(duì)的在線API文檔工具，也支持用docker自建文檔服務(wù),，不過為了方便演示,，我直接用了平臺(tái)在線服務(wù)。官網(wǎng)地址：markdown語法來寫API文檔,、數(shù)據(jù)字典文檔,、技術(shù)文檔、在線excel文檔,。但像我這種資深的懶人程序員，其實(shí)更看重的是showdoc的自動(dòng)化生成文檔的特性,，它可以從代碼注釋中自動(dòng)生成API文檔,，或者搭配RunApi客戶端（類似postman的api調(diào)試工具）一邊調(diào)試接口、一邊自動(dòng)生成文檔,。 初識(shí) ShowDocShowDoc新建項(xiàng)目可選常規(guī)的API文檔,、在線表格,、或者單頁文檔（不支持目錄分層），允許對(duì)項(xiàng)目文檔設(shè)置訪問密碼,，自定義域名,，這里并不是真正意義上的“域名”，只是在文檔服務(wù)域名后加了一級(jí)目錄,，例如：
 Postman、swagger的API接口配置Json文件,。提供的開放API是自動(dòng)化生成文檔的關(guān)鍵,，先記住有api_key、api_token這兩個(gè)屬性,，后邊詳細(xì)講,。 ShowDoc預(yù)置了幾種文檔模板，也可以把自定義的文檔存為模板,；支持在線Mock服務(wù),，提前定義好接口的數(shù)據(jù)格式，先提供在線臨時(shí)接口,，這樣就可以和前端同步開發(fā),，后邊無縫切換；還有個(gè)簡單的API在線測(cè)試功能,。  word,、Markdown兩種格式。  showdoc很普通啊,，好像沒什么特別的地方,，上邊的這些文檔都是需要我們手動(dòng)書寫的，比較繁瑣不推薦這么搞,，接下來咱們看看如何自動(dòng)化生成文檔,。自動(dòng)生成文檔showdoc有三種自動(dòng)生成API文檔的方式：
Runapi是一個(gè)以接口為核心的開發(fā)測(cè)試工具（可以看做是Postman的精簡版）。目前客戶端支持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格式的文檔,。 程序員內(nèi)點(diǎn)事”,，分別建三個(gè)接口“點(diǎn)在”、“在看”,、“關(guān)注”,，緊接著快速生成參數(shù)和響應(yīng)結(jié)果數(shù)據(jù)并保存,。 文檔鏈接設(shè)置訪問密碼，不填默認(rèn)是公開的,，復(fù)制文檔鏈接在瀏覽器中打開,，看到API接口文檔已經(jīng)生成。runapi還有全局參數(shù),、環(huán)境隔離,。其實(shí)Postman也支持這樣的功能，不過畢竟不是國內(nèi)產(chǎn)品,，網(wǎng)絡(luò)訪問等方面很受限制,。Runapi支持接口執(zhí)行前后的腳本,，比如響應(yīng)數(shù)據(jù)的斷言測(cè)試,，彈框顯示都挺好用的。代碼注釋showdoc,，但這種我并不太喜歡,，主要是侵入性比較強(qiáng)，讓代碼的閱讀性變的比較差,，一坨坨看著很不爽,。* showdoc * @catalog 測(cè)試文檔/用戶相關(guān) * @title 用戶注冊(cè) * @description 用戶注冊(cè)的接口 * @method post * @url https://www./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這兩個(gè)屬性嘛,，現(xiàn)在派上用場了，下邊我用windows環(huán)境演示,。
showdoc_api.sh，替換我們api_key和api_token變量值,，URL如果沒搭建自己的文檔服務(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ù)字典showdoc也是支持的，先下載官方提供的腳本
api_key、api_token等信息,，直接執(zhí)行后數(shù)據(jù)庫表結(jié)構(gòu)信息同步到showdoc,。
開放APIshowdoc開放了文檔編輯的API,，我們可以在代碼中調(diào)用API創(chuàng)建、編輯文檔,。這樣使用的場景就比較靈活了,。
showdoc對(duì)應(yīng)的項(xiàng)目里已經(jīng)創(chuàng)建了名字為xiaofu的文檔,。
說兩句showdoc現(xiàn)有的功能postman基本都支持,，但postman功能過于繁雜不夠簡潔，加上網(wǎng)絡(luò)條件等諸多限制,，協(xié)同辦公的效率并不高,，而Runapi配合showdoc在某些場景下能夠很大程度上提升我們開發(fā)交付的效率，所以能自動(dòng)生成的絕對(duì)不手寫,！ |
|
|
