什么是apidoc
apidoc是一個(gè)輕量級(jí)的在線REST接口文檔生成系統(tǒng)，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者按照要求書寫相關(guān)注釋，就可以生成可讀性好、界面美觀的在線接口文檔。
快速開始
-
安裝依賴
-
安裝nodejs https://nodejs.org/官網(wǎng)下載.msi文件；
測(cè)試是否安裝成功 npm -v - npm的安裝。由于新版的NodeJS已經(jīng)集成了npm，所以之前npm也一并安裝好了。同樣可以使用cmd命令行輸入"npm -v"來測(cè)試是否成功安裝。如下圖，出現(xiàn)版本提示便OK了。
-
安裝apidoc
利用npm進(jìn)行安裝
npm install apidoc -g
安裝速度和網(wǎng)速有關(guān)，最多1到2分鐘，
apidoc -v 可以查看版本信息
安裝好后在
C:\Users\admin\AppData\Roaming\npm\node_modules\apidoc
image.png
-
apidoc配置
打開example文件夾apidoc.json為配置文件,修改參數(shù)為自己的項(xiàng)目信息。
{
"name": "apidoc-example",
"version": "0.3.0",
"description": "apidoc example project",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1",
"sampleUrl": "https://api.github.com/v1",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
},
"template": {
"withCompare": true,
"withGenerator": true
}
}
將 apidoc.json 拷貝到需要生成文檔的目錄下
image.png
然后按照文檔說明做代碼注釋
/**
* @api {get} /sguoshan_api/Logon 獲取用戶信息
* @apiVersion 1.0.0
* @apiName Logon
* @apiGroup User
* @apiPermission 所有已注冊(cè)用戶
* @apiPrivate
* @apiDescription 與0.9.0相比安全性提高
*
* @apiParam {String} username 用戶名稱/郵箱/會(huì)員號(hào)
* @apiParam {Number} password 用戶密碼
* @apiExample 使用示例:
* http://api.guoshanchina.com/sguoshan_api/Logon?username=911117&password=123456
*
* @apiSuccess {Number} id The Users-ID.
* @apiSuccess {Date} registered Registration Date.
* @apiSuccess {Date} name Fullname of the User.
* @apiSuccess {String[]} nicknames List of Users nicknames (Array of Strings).
* @apiSuccess {Object} profile Profile data (example for an Object)
* @apiSuccess {Number} profile.age Users age.
* @apiSuccess {String} profile.image Avatar-Image.
* @apiSuccess {Object[]} options List of Users options (Array of Objects).
* @apiSuccess {String} options.name Option Name.
* @apiSuccess {String} options.value Option Value.
*
* @apiSuccessExample 成功 return ():
{
"msg": "獲取成功",
"status":"200",
"data":{
"id":"123",
"name":"shmily"
}
}
* @apiError NoAccessRight 只用登陸成功才能訪問.
* @apiError UserNotFound 用戶 <code>id</code> 錯(cuò)誤.
* @apiErrorExample 失敗 return ():
* HTTP/1.1 401 Not Authenticated
* {
* "msg": "沒有權(quán)限","status":"401"
* }
*/
function getUser() { return; }
在命令行中
切換到項(xiàng)目apidoc.json的上一級(jí)（api目錄）
d:
cd www/shop/Web
apidoc -i api/ -o apidoc/
成功生成
運(yùn)行后在api的同級(jí)目錄能夠看到生成了apidoc的文件夾。雙擊文件夾下的index.html，就能看到文檔了。
image.png
