介紹
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...
如果你的專案下太多檔案，則可能導致指令碼掃描很慢。推薦把指令碼放到需要生成註釋的那個目錄裡。一般來講，一個專案不會所有目錄都需要生成文件的