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

问题

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

参考

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