apiDoc自动生成api文档

在自定生成api文档方面以前都是使用swagger.json结合swagger工具来生成文档，偶然发现了apidoc这个生成api的工具，发现使用起来比swagger更加简单，下面整理一下使用过程：

1、安装

首先通过npm全局安装apidoc

$ npm install apidoc -g

2、使用

使用的时候最主要是参考官方文档 ，apidoc文档，文档中清晰的记录了怎么使用的过程，最好也要看一下apidoc的github地址，从哪里你可以看到一个简单的example，

下面就是利用github上apidoc的example来作为实例，example的结构如下：

weifandeMacBook-Pro:example weifan$ ls
_apidoc.js    apidoc.json    example.js    footer.md    header.md

3、生成api文档

首先我们在执行apidoc命令的目录下，新建一个apiDocs文件，命令如下：

mkdir apiDocs

然后执行生成api文档命令，如下：

$ apidoc -i example/ -o apiDocs/

其中apidoc 参数如下：

• -i
  读取用于生成文档的目录，比如src目录
• -o
  生成api文档静态页面的目录
• -t
  自定义的模板目录，默认使用apiDoc的模板
• -f “.*\.java$”
  解析符合正则表达式的文件
• -h
  显示帮助信息

在你运行上面命令的时候如果example文件夹下没有apidoc.json这个文件，则会出现一下警告信息：

warn: Please create an apidoc.json configuration file.
info: Done.

说明你没有配置生成api的配置文件（如果没有其实也是可以生成的只不过是默认格式）。

此时你会看到apiDocs文件夹下回有生成的index.html文件，在浏览器中运行这个文件，你就会看到你生成的api文档了。

5、配置 apidoc.json

在执行 apidoc 命令的目录执行创建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
  }
}

• name
  文档内容的最大标题
• version
  文档的版本号，一般保持在最新
• description
  文档的描述
• title
  显示网页的title
• url
  每个api地址前缀
• sampleUrl
  请求示例工具的地址前缀，当有此项时，会出现该工具
• header/footer
  文档的头部和尾部
  • title
    头/尾部标题
  • filename
    头部markdown文件
• template
  • withCompare
    自动生成版本比较功能的文件，默认 true
  • withGenerator
    生成默认的apidoc版权，默认 true

6、apiDoc 注解

下面是apidoc的注解，最主要还是要参照官方文档。

• @api {method} path [title]
  method 请求方式: get/post/put…
  path User/register
  title 标题
• @apiDescription text
  api描述
• @apiError [(group)] [{type}] field [description]
• @apiErrorExample [{type}] [title]
  example
• @apiExample [{type}] title
  example
• @apiGroup name
• @apiHeader [(group)] [{type}] [field=defaultValue] [description]
• @apiHeaderExample [{type}] [title]
  example
• @apiIgnore [hint]
• @apiName name
• @apiParam [(group)] [{type}] [field=defaultValue] [description]
• @apiParamExample [{type}] [title]
  example
• @apiPermission name
• @apiSampleRequest url
• @apiSuccess [(group)] [{type}] field [description]
• @apiSuccessExample [{type}] [title]
  example
• @apiUse name
• @apiVersion version

问题

1. 无法生成带有历史版本比较功能
   必须同时加上 @apiVersion @apiName @apiGroup 这个三个注解
2. @apiName后面不要使用中文介绍，必须要使用英文，不然这个api可能会被隐藏。详见：https://github.com/apidoc/apidoc/issues/431
3. 最好不要包含一些特殊字符，特殊字符可能会导致编译有问题

参考

官方文档: http://apidocjs.com
官方示例: https://github.com/apidoc/apidoc/tree/master/example