如何利用showdoc自動生成API文檔

介紹

showdoc是一個適合IT團隊的文檔工具，閱讀本文前須要對showdoc有基本瞭解 。基本介紹可看：https://www.showdoc.cc/help

對於寫API文檔這件事，雖說文本編輯軟件或者接口管理軟件能在某種程度上提升咱們的效率，但咱們依然能夠試圖藉助技術的力量，更自動化地生成API文檔，釋放本身的生產力。
爲此，showdoc官方提供了一種自動化解決方案。在代碼裏編寫特定格式的程序註釋，而後showdoc經過讀取這些註釋來自動生成文檔。因爲這種方式不跟特定的語言耦合，所以它的使用範圍至關普遍，可用支持c++、java、php、node、python等等常見的主流語言。
採用這種方式，儘管咱們在第一次填寫註釋的時候可能會有些繁瑣，可是它後期帶來的可維護性是很是高的。代碼變更後，不須要再額外登陸showdoc，直接在代碼裏修改註釋便可。同時自動化的腳本也能夠加入持續集成或者某些自動化工程裏，讓「寫API文檔」這件事如"單元測試"般歸入工程工做流裏面。

windows下使用指引

windows沒法直接運行sh腳本，須要額外下載軟件。
推薦下載git for windows：https://git-scm.com/download/win 下載後直接雙擊安裝便可。
若是從官網下載比較慢，可用考慮下載由第三方開發者維護的國內版(showdoc官方不保證其長期穩定)：
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 ，這個須要用戶自行填寫。關於這兩個變量的取值，請登陸showdoc，進入某個項目的設置，點擊開放API，即可以看到說明。showdoc_api.sh生成的文檔會放進你填寫的這個項目裏。除了api_key 和 api_token ，還有一個url變量。若是是使用www.showdoc.cc ，則不須要修改。若是是使用開源版showdoc，則須要將地址改成http://xx.com/server/?s=/api/open/fromComments 其中，別忘記了url裏含server目錄。
填寫完畢，保存。而後直接雙擊運行，腳本會自動遞歸掃描本目錄和子目錄的全部文本代碼文件，並生成API文檔。
爲了方便測試，官方還提供了一個例子。請下載：
https://www.showdoc.cc/script/api_demo.test
下載後，把api_demo.test文件放在showdoc_api.sh所在的目錄或者子目錄下。運行的時候它便會生成文檔到你指定的項目地址中。
若是你想參考官方demo是怎麼寫的，可用鼠標右擊api_demo.test，選擇編輯。仿照此種寫法，在你的項目中插入相似的註釋，也能達到自動生成文檔的效果。詳細語法會在文章後面部分說明。

若是你想應用到其餘項目，能夠把showdoc_api.sh複製一份到其餘項目中。使用方法和前面同樣。

Linux/Mac下使用指引

先cd進入你的項目目錄，命令行模式下輸入：

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

下載完畢，編輯

vi showdoc_api.sh

腳本內容的前面有兩個變量，api_key 和 api_token ，這個須要用戶自行填寫。關於這兩個變量的取值，請登陸showdoc，進入某個項目的設置，點擊開放API，即可以看到說明。showdoc_api.sh生成的文檔會放進你填寫的這個項目裏。除了api_key 和 api_token ，還有一個url變量。若是是使用 www.showdoc.cc ，則不須要修改。若是是使用開源版showdoc，則須要將地址改成http://xx.com/server/?s=/api/... ，其中，別忘記了url裏含server目錄。

保存文件後。執行如下命令，腳本會自動遞歸掃描本目錄和子目錄的全部文本代碼文件，並生成API文檔。

chmod +x showdoc_api.sh
./showdoc_api.sh

爲了方便測試，官方還提供了一個例子。請下載：
wget https://www.showdoc.cc/script/api_demo.test

下載後，把api_demo.test文件放在showdoc_api.sh所在的目錄或者子目錄下。運行的時候它便會生成文檔到你指定的項目地址中。
若是你想參考官方demo是怎麼寫的，可用vi命令打開api_demo.test。仿照此種寫法，在你的項目中插入相似的註釋，也能達到自動生成文檔的效果。詳細語法會在文章後面部分說明。

若是你還想應用到其餘項目，能夠把showdoc_api.sh複製一份到其餘項目中。使用方法和前面同樣。
或者不轉移位置，直接經過參數指定掃描目錄。如

./showdoc_api.sh /myapp/demo/

語法說明

一個標準語法例子：

/**
    * showdoc
    * @catalog 測試文檔/用戶相關
    * @title 用戶登陸
    * @description 用戶登陸的接口
    * @method get
    * @url https://www.showdoc.cc/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
    */

語法說明

@catalog // 生成文檔要放到哪一個目錄。若是隻是二級目錄，則直接寫目錄名字。若是是三級目錄，而須要寫二級目錄/三級目錄，即用 / 隔開。  
@title   //表示生成的文檔標題 
@description // 是文檔內容中對接口的描述信息  
@method  //接口請求方式。通常是get或者post 
@url  //接口URL  
@param //參數表格說明。一行註釋對應着表格的一行。用空格或者tab符號來隔開每一列信息。  
@return  //返回內容。請把返回內容壓縮在同一行內。若是是json，程序會自動進行格式化展現。 若是是非json內容，則原樣展現。
@return_param //返回參數的表格說明。一行註釋對應着表格的一行。用空格或者tab符號來隔開每一列信息。
@remark  //備註信息 
@number   //可選。文檔的序號。

其餘信息

請嚴格按照咱們的語法來填寫程序註釋。若是格式不對，則可能引起未知的解析錯誤。

出於數據安全考慮，showdoc不容許直接經過代碼刪除文檔。只能新增或者修改。因此，若是你要刪除文檔，請登陸showdoc網頁端完成。

本腳本只能經過特定的程序註釋來生成文檔，使用範圍有限。若是你是想經過其餘方式自由地生成文檔，如經過word、經過博客軟件等，請參考咱們更自由的開放API：https://www.showdoc.cc/page/1...

若是你的項目下太多文件，則可能致使腳本掃描很慢。推薦把腳本放到須要生成註釋的那個目錄裏。通常來說，一個項目不會全部目錄都須要生成文檔的