利用apidoc维护api接口文档

什么是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/Webapidoc -i api/ -o apidoc/

成功生成

运行后在api的同级目录能够看到生成了apidoc的文件夹。双击文件夹下的index.html，就能看到文档了。

image.png