標(biāo)簽（空格分隔）： node.js
apidoc可以根據(jù)代碼注釋生成web api文檔，支持大部分主流語言java javascript php coffeescript erlang perl python ruby go...，相對而言瀑凝，web接口的注釋維護(hù)起來更加方便架忌，不需要額外再維護(hù)一份文檔。
apidoc從注釋生成靜態(tài)html網(wǎng)頁文檔丁恭，不僅支持項目版本號曹动，還支持api版本號。
安裝
主頁: http://apidocjs.com
github: https://github.com/apidoc/apidoc
可以使用npm install apidoc -g進(jìn)行安裝涩惑，目前0.12.x/4.0都可以使用仁期。
apidoc支持Grunt桑驱，主頁 https://github.com/apidoc/grunt-apidoc
- 在項目中使用
npm install grunt-apidoc --save-dev安裝竭恬。 - 在
Gruntfile.js添加grunt.loadNpmTasks('grunt-apidoc');。 - 配置
grunt task
apidoc: {
myapp: {
src: "app/",
dest: "apidoc/"
}
}
// 在sails中2和3可以直接添加一個task
module.exports = function(grunt) {
grunt.config.set('clean', {
apidoc: {
myapp: {
src: "app/",
dest: "apidoc/"
}
}
});
grunt.loadNpmTasks('grunt-apidoc');
};
用法
可以在shell中執(zhí)行apidoc -h就可以看到很多用法熬的。
apidoc help
下面講講常用的幾個參數(shù)痊硕。
// 典型用法
apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$"
-i 表示輸入，后面是文件夾路徑
-o 表示輸出押框，后面是文件夾路徑
默認(rèn)會帶上-c岔绸，在當(dāng)前路徑下尋找配置文件(apidoc.json)，如果找不到則會在package.json中尋找 "apidoc": { }
-f 為文件過濾橡伞，后面是正則表達(dá)式盒揉，示例為只選著js文件
與-f類似，還有一個 -e 的選項兑徘，表示要排除的文件/文件夾刚盈，也是使用正則表達(dá)式
如果項目輸入和輸出穩(wěn)定，可以編輯Makefile保存命令挂脑，例如：
docs:
@apidoc -i api/ -o doc/apidoc
之后使用make docs即可生成/更新api文檔藕漱。
配置
項目配置
apidoc.json示例：
{
"name" : "mysails",
"version": "1.0.0",
"title": "mysails", // 瀏覽器標(biāo)題
"description": "xun's test project"
}
如果放入package.json中，相同的字段可以直接使用package.json的定義崭闲，額外的字段放入apidoc下
{
"name": "mysails",
"private": true,
"version": "1.0.0",
"description": "xun's test project",
"apidoc": {
"title": "mysails"
},
...
}
代碼注釋
apidoc支持如下關(guān)鍵字
@api {method} path [title]
只有使用@api標(biāo)注的注釋塊才會在解析之后生成文檔肋联，title會被解析為導(dǎo)航菜單(@apiGroup)下的小菜單
method可以有空格，如{POST GET}
@apiGroup name
分組名稱刁俭，被解析為導(dǎo)航欄菜單
@apiName name
接口名稱橄仍，在同一個@apiGroup下，名稱相同的@api通過@apiVersion區(qū)分牍戚，否者后面@api會覆蓋前面定義的@api
@apiDescription text
接口描述侮繁，支持html語法
@apiVersion verison
接口版本，major.minor.patch的形式
@apiIgnore [hint]
apidoc會忽略使用@apiIgnore標(biāo)注的接口翘魄，hint為描述
@apiSampleRequest url
接口測試地址以供測試鼎天，發(fā)送請求時，@api method必須為POST/GET等其中一種
@apiDefine name [title] [description]
定義一個注釋塊(不包含@api)暑竟，配合@apiUse使用可以引入注釋塊
在@apiDefine內(nèi)部不可以使用@apiUse
@apiUse name
引入一個@apiDefine的注釋塊
@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
用法基本類似斋射，分別描述請求參數(shù)育勺、頭部，響應(yīng)錯誤和成功
group表示參數(shù)的分組罗岖，type表示類型(不能有空格)涧至，入?yún)⒖梢远x默認(rèn)值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
用法完全一致，但是type表示的是example的語言類型
example書寫成什么樣就會解析成什么樣桑包，所以最好是書寫的時候注意格式化南蓬，(許多編輯器都有列模式，可以使用列模式快速對代碼添加*號)
@apiPermission name
name必須獨一無二哑了，描述@api的訪問權(quán)限赘方，如admin/anyone
示例:
定義一個200的返回結(jié)果
/** js
* @apiDefine CODE_200
* @apiSuccess (Reponse 200) {number} code 200
* @apiSuccess (Reponse 200) {json} [data='""'] 如果有數(shù)據(jù)返回
* @apiSuccessExample {json} Response 200 Example
* HTTP/1.1 200 OK
* {
* "code": 200,
* "data": ""
* }
*/
定義一個500的返回結(jié)果
/**
* @apiDefine CODE_500
* @apiSuccess (Response 500) {number} code 500
* @apiSuccess (Response 500) {string} [message] error description
* @apiSuccessExample {json} Response 500 Example
* HTTP/1.1 500 Internal Server Error
* {
* "code": 500
* "message": "xxx"
* }
*/
定義接口
/**
* @apiDefine Data
*
* @apiParam (data) {string} [firstname] Optional Firstname of the User.
* @apiParam (data) {string} lastname Mandatory Lastname.
* @apiParam (data) {string} country="cn" Mandatory with default value "DE".
* @apiParam (data) {number} [age=18] Optional Age with default 18.
*/
/**
* @api {POST GET} /api/test/hello[/:id] /api/test/hello[/:id]
* @apiName test api
* @apiGroup Hello World
* @apiVersion 1.0.0
* @apiDescription just a test
* @apiPermission anyone
* @apiSampleRequest http://test.github.com
*
* @apiParam {number} [id] any id
* @apiParam {json} data object
* @apiUse Data
*
* @apiParamExample {json} Request Example
* POST /api/test/hello/1
* {
* "data": {
* "firstname": "test",
* "lastname": "sails",
* "country": "cn"
* }
* }
*
* @apiUse CODE_200
* @apiUse CODE_500
*/
最后生成文檔之后，結(jié)果如下所示
示例
