安装并使用 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, '_');

发表评论

电子邮件地址不会被公开。 必填项已用*标注

10 + 16 =