利用ShowDoc自動生成api接口文檔

 

最近在做新項目，感覺寫完一個接口 還要去再寫一遍api文檔 挺浪費時間的，所以借用ShowDoc的api開放功能 自動生成api文檔。

 

首先 去 https://www.showdoc.cc/ 注冊一個賬戶，新建一個項目，

建立新項目后，選擇該項目，打開，進入項目界面

然后點擊項目，下拉選擇項目設置，

可以看到開放API，下面還有Api文檔，數據字典文檔

Windows系統安裝步驟：

自動化生成API文檔，首先需要下載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 ，這個需要用戶自行填寫。關於這兩個變量的取值，請登錄showdoc，進入某個項目的設置，點擊開放API，便可以看到說明。showdoc_api.sh生成的文檔會放進你填寫的這個項目里。除了api_key 和 api_token ，還有一個url變量。如果是使用www.showdoc.cc ，則不需要修改。如果是使用開源版showdoc，則需要將地址改為http://xx.com/server/index.php?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/index.php?s=/api/open/fromComments ，其中，別忘記了url里含server目錄。

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

1. chmod +x showdoc_api.sh
2. ./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/

語法說明

一個標准語法例子：

1. /**
2. * showdoc
3. * @catalog 測試文檔/用戶相關
4. * @title 用戶登錄
5. * @description 用戶登錄的接口
6. * @method get
7. * @url https://www.showdoc.cc/home/user/login
8. * @param username 必選 string 用戶名
9. * @param password 必選 string 密碼
10. * @param name 可選 string 用戶昵稱
11. * @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吳系掛","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
12. * @return_param groupid int 用戶組id
13. * @return_param name string 用戶昵稱
14. * @remark 這里是備注信息
15. * @number 99
16. */

關鍵字	說明
@catalog	生成文檔要放到哪個目錄。如果只是二級目錄，則直接寫目錄名字。如果是三級目錄，而需要寫二級目錄/三級目錄，即用/隔開。如”一層/二層/三層”
@title	表示生成的文檔標題
@description	是文檔內容中對接口的描述信息
@method	接口請求方式。一般是get或者post
@url	接口URL。不要在URL中使用&符號來傳遞參數。傳遞參數請寫在參數表格中
@param	參數表格說明。一行注釋對應着表格的一行。用空格或者tab符號來隔開每一列信息。
@json_param	可選。當請求參數是json的時候，可增加此標簽。請把json內容壓縮在同一行內。
@return	返回內容。請把返回內容壓縮在同一行內。如果是json，程序會自動進行格式化展示。 如果是非json內容，則原樣展示。
@return_param	返回參數的表格說明。一行注釋對應着表格的一行。用空格或者tab符號來隔開每一列信息。
@remark	備注信息
@number	可選。文檔的序號。