在nodejs上使用APIDOC生成接口文档的方法
2016-08-25 23:51:10
众所周知， 写代码虽然杀脑细胞， 但是写完了，实现了功能就好了。 但是写很多时候需要我们写完了代码还要写文档， 是不是瞬间软了？前两天发现了一个api文档的生成去-APIDOC. 真心不错.下面是在nodejs平台上操作的步骤
1. node -v //查看node版本
2. npm -v //查看是否安装了npm
3. npm install apidoc -g //全局安装,生成了node_module文件夹
4. apidov -h //查看apidoc是否生成完成
5. 新建 apidoc.josn 与test.php /test.js
apidoc.josn中的代码
{
"name" : "mysails",
"version": "1.0.0",
"title": "mysails", // 浏览器标题
"description": "xun's test project"
}
test.js 中的代码
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
代码注释
apidoc支持如下关键字
api {method} path [title]
只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单
method可以有空格，如{POST GET}
@apiGroup name
分组名称，被解析为导航栏菜单
@apiName name
接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api
@apiDescription text
接口描述，支持html语法
@apiVersion verison
接口版本，major.minor.patch的形式
@apiIgnore [hint]
apidoc会忽略使用@apiIgnore标注的接口，hint为描述
@apiSampleRequest url
接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种
@apiDefine name [title] [description]
定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块
在@apiDefine内部不可以使用@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]
用法基本类似，分别描述请求参数、头部，响应错误和成功
group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
用法完全一致，但是type表示的是example的语言类型
example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)
@apiPermission name
name必须独一无二，描述@api的访问权限，如admin/anyone
6 . apidoc -i myapp/ -o apidoc/ -t mytemplate/ 生成api文档。
// 典型用法
apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$"
-i 表示输入，后面是文件夹路径
-o 表示输出，后面是文件夹路径
默认会带上-c，在当前路径下寻找配置文件(apidoc.json)，如果找不到则会在package.json中寻找 "apidoc": { }
-f 为文件过滤，后面是正则表达式，示例为只选着js文件
与-f类似，还有一个 -e 的选项，表示要排除的文件/文件夹，也是使用正则表达式
如果看到“success: Done.”说明生成成功 ，到 apidoc目录下打开index.html查看生成的文档.
大功告成！
