Smart-doc的腳本生成線上文檔(精簡官方文檔描述)

Smart-doc優點：

        無侵入的接口文檔、線上文檔生成器。三種生成文檔方式。對于程式代碼開發中隻需要加注釋（符合一定的文法，五分鐘可掌握）就能生成線上文檔。可以支援c++、java、php、node等等常見的主流語言。

Smart-doc缺點：

        注重文檔内容，不提供測試、mock等功能，如果要使用測試mock等功能需要先用RunApi工具手動維護接口内容，而大部分比如postman、apifox等項目管理工具都是支援直接導入swagger文檔自動生成的。而且swagger本身也提供了一定的接口測試功能，如果有測試的需要的話swagger可能是更好的選擇。

 如何使用：

        ShowDoc，該連接配接指向官方文檔闡述，字太多，覺得我闡述的不好的可以看官方的。以下我精簡歸納一下

使用腳本實作：

  前提環境：windows系統、git（下載下傳git for windows：Git - Downloading Package）、shell腳本（https://www.showdoc.cc/script/showdoc_api.sh）

怎麼寫注釋：（idea建立Live Template就能一勞永逸了）

//注釋示例

/**
	* showdoc
	* @catalog 測試文檔/使用者相關
	* @title 使用者登入2
	* @description 使用者登入的接口（參數以純json的方式送出）
	* @method post
	* @url https://www.showdoc.com.cn/home/user/login2
	* @json_param {"username":"test","password":"***"} 
	* @param username 必選 string 使用者名  
	* @param password 必選 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 function login2(){
	
	}
           

怎麼生成線上文檔：

1.    showdoc_api.sh放在需要生成文檔的代碼目錄下，腳本會周遊子目錄的。（我是把要生成的文檔的檔案放到一個指定目錄裡面，這樣很節省腳本執行時間）
2. 編輯showdoc_api.sh，替換成自己的api_key 和 api_token，公共版的url不用動，儲存

   

3.   擷取api_key 和 api_token（生成對應的項目目錄，每個項目都又子集的key和token）  
   1. 如果你的項目是在showdoc網頁上建立的，則請登入showdoc，進入某個項目的設定，點選開放API，便可以看到api_key 和 api_token的說明
   2. 如果你的項目是在runapi用戶端（ ShowDoc ） 上建立的，則可以點選runapi用戶端最左側的菜單欄，選擇“項目”。然後點選其中一個項目的“自動生成”按鈕，便可以看到api_key 和 api_token的說明
4. 輕按兩下 運作showdoc_api.sh腳本，生成線上文檔了，去自己的smart-doc賬戶上看看吧 。