什么是apidoc
apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档。
快速开始
-
安装依赖
-
安装nodejs https://nodejs.org/官网下载.msi文件；
测试是否安装成功 npm -v - npm的安装。由于新版的NodeJS已经集成了npm，所以之前npm也一并安装好了。同样可以使用cmd命令行输入"npm -v"来测试是否成功安装。如下图，出现版本提示便OK了。
-
安装apidoc
利用npm进行安装
npm install apidoc -g
安装速度和网速有关，最多1到2分钟，
apidoc -v 可以查看版本信息
安装好后在
C:\Users\admin\AppData\Roaming\npm\node_modules\apidoc
image.png
-
apidoc配置
打开example文件夹apidoc.json为配置文件,修改参数为自己的项目信息。
{
"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 所有已注册用户
* @apiPrivate
* @apiDescription 与0.9.0相比安全性提高
*
* @apiParam {String} username 用户名称/邮箱/会员号
* @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> 错误.
* @apiErrorExample 失败 return ():
* HTTP/1.1 401 Not Authenticated
* {
* "msg": "没有权限","status":"401"
* }
*/
function getUser() { return; }
在命令行中
切换到项目apidoc.json的上一级（api目录）
d:
cd www/shop/Web
apidoc -i api/ -o apidoc/
成功生成
运行后在api的同级目录能够看到生成了apidoc的文件夹。双击文件夹下的index.html，就能看到文档了。
image.png
