安装并使用 apidoc

apidoc是一个轻量级的在线REST接口文档生成系统，可以根据其特定的规则的代码注释来生成静态网页。首先看下它生成的文档界面和风格。

apidoc支持多种主流的编码语言，包括Java、C、C#、PHP和Javascript。一般情况下，语言会有多种注释方法，例如就Java中有普通风格的多行注释和Javadoc风格的注释。apidoc并不支持所有的注释，譬如Java仅中支持Javadoc风格的注释。首先要说明的是，apidoc并不具备语义识别能力，它不会发现代码中是否有BUG，它仅仅通过文件后缀来判断语言类型。

安装

apidoc是基于nodeJs平台，在安装apidoc之前，需要先 安装nodeJs。

在控制台或命令行中输入：

npm install apidoc -g

使用

在项目根目录建立文件 apidoc.json，内容如下：

{
  "name": "demo", 
  "version": "1.0.0",
  "description": "这是一个简单的apidoc的demo",
  "title": "demo",
  "url" : "https://api.github.com/v1"
}

编写注释：

/**
 * 列表
 * @param Request $request
 * @return mixed
 *
 * @api {get} customer 列表
 * @apiGroup 客户
 * @apiParam {string} search
 * @apiSuccessExample {json} 返回
 * {
 *      total,
 *      per_page,
 *      current,
 *      data: [
 *          {
 *              name,
 *              code,
 *              contacts,
 *              telephone,
 *          },
 *      ]
 * }
 */

以上注释只有 @api 开头的才能被 apidoc 识别，其他注释都是标准注释。更多文档属性见 官方文档

apiGroup 不能使用中文

默认使用中文时，中文会被 _ 代替，若要解决，编辑如下文件：

  • windows C:\Users\Administrator\AppData\Roaming\npm\node_modules\apidoc\node_modules\apidoc-core\lib\workers\api_group.js
  • linux（使用 nvm 安装 node） ~/.nvm/versions/node/v8.11.3/lib/node_modules/apidoc/node_modules/apidoc-core/lib/workers/api_group.js （其中 v8.11.3 根据自己安装的版本更换）
  • mac /usr/local/lib/node_modules/apidoc/node_modules/apidoc-core/lib/workers/api_group.js

注释掉以下行：

// group = group.replace(/[^\w]/g, '_');