一、apidoc简单介绍
apidoc根据你源码中的api注解(apidoc自己的注解)，创建说明文档，创建出的说明文档为html格式，能够发布出去，apidoc是基于nodejs，代码开源，官网地址，github地址，目前最新提交是2017年5月，貌似已经停止维护，不过整个代码逻辑很简单，适合定制，apidoc基本支持所有语言的文档生成，C#、Java、JavaScript、PHP、Python，具体可参加官方说明
二、apidoc安装
1.首先查看是否有nodejs环境，node -v ,查看node版本，如果不能执行，需要安装nodejs，nodejs下载地址https://nodejs.org/en/download/，可以根据具体环境选择版本，win可以下载压缩包，解压后，把解压文件夹的根目录配置到path里即可，linux一般都会自带nodejs,如果没有可yum install nodejs -y ,不同的linux版本使用不同的在线安装命令，这里列出CentOS，如果不能在线安装，那就只能自己下了，这里不在赘述
2.安装完nodejs环境后，会自带npm,npm为nodejs包管理工具，安装apidoc :npm install apidoc -g, 安装完成后，使用apidoc -h,查看是否安装成功
三、apidoc使用
1.添加apidoc.json
在项目中创建apidoc.json,位置建议在项目根目录，也可自选，自选位置的话，需要在运行apidoc命令时带上位置参数
apidoc.json内容示例
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}各参数含义
| 参数 | 说明 |
|---|---|
| name | 项目名称 |
| version | 项目版本 |
| description | 项目描述 |
| title | 浏览器标题 |
| url | api路径前缀，会自动拼接到@api 路径前，可以设置为空串 |
| sampleUrl | 如果设置，将显示用于测试api方法（发送请求）的表单。有关详细信息，请参阅@apiSampleRequest。 |
| header | api文档的头 |
| title | 左侧导航栏中显示的文本 |
| filename | 内容文件，为md(markdown)格式，可以写前言等项目边角信息 |
| footer | 与header相同，只不过一个在头，一个在尾，不再赘述 |
| title | |
| filename | |
| order | 用于排序的，没有详细研究 |
带header示例
{
"name": "onsite接口说明文档",
"version": "1.0.0",
"description": "",
"title": "onsite接口说明文档",
"url":"",
"header": {
"title": "My own header title",
"filename": "api-template/header.md"
},
"footer": {
"title": "My own footer title",
"filename": "api-template/footer.md"
}
}
2.添加api注解
api注解是apidoc自己定义的一套，用于生成文档的注解，注解太多就不一一介绍了，大家可以参考官说明http://apidocjs.com/#param-api，这里仅说明基础使用.
apidoc是按注释块解析注解的，在java中一个注释块形如(以下为两个注解块)：
/**
* @api {get} /user/{id} 获取用户信息
*/
/**
* @api {put} /user/{id} 修改用户信息
*/
apidoc仅解析含有@api或者@apiDefine的注释块，@apiDefine一个注释块中仅能有一个，@apiDefine可以定义一些通用的内容，比如通用的请求参数，返回值，错误列表等 ；@api 就不用多说了，用来定义一个api,需要注意的是，@apiGroup和@apiName是必须的，@apiGroup定义的是左侧导航，@apiName 会拼接到访问路径中，大家试下就会明白
@apiGroup是不支持中文的，需要和@apiDefine配合使用，例如：
/**
* @apiDefine User 用户模块
*
*/
/**
* @api {get} /user/{id} 获取用户信息
* @apiGroup User
* @apiName Get-user
*
*/以下为官网一个较为完整的例子
{
"name": "example-inherit",
"version": "0.1.0",
"description": "apiDoc inherit example"
}/**
* @apiDefine UserNotFoundError
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiUse UserNotFoundError
*/
/**
* @api {put} /user/ Modify User information
* @apiName PutUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
* @apiParam {String} [firstname] Firstname of the User.
* @apiParam {String} [lastname] Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
*
* @apiUse UserNotFoundError
*/生成文档地址：http://apidocjs.com/example_inherit/#api-User
从例子可以看出，apidoc不在乎你把注释写在哪里，不过还是推荐写在接口所在位置
3.执行apidoc命令
以上两步完成后，就可以执行apidoc命令生成文档了，打开命令行，切换到项目根目录，执行apidoc -f "正则" -i 输入路径 -o 文档输出路径 ，大家可以根据自己情况选取参数，执行apidoc -h 可列出各种参数用法以及默认值
| 参数 | 说明 |
|---|---|
| -h，--help | 显示帮助信息 |
| -f，--file-filters | 正则表达式过滤应该解析的文件（可以使用多个-f）。默认值：.cs .dart .erl .go .java .js .php .py .rb .ts。示例（仅解析.js和.ts文件）： apidoc -f ".*\.js$" -f ".*\.ts$" |
| -e, --exclude-filters | 正则排除不需要解析的文件，可是使用多个 |
| -i, --input | 项目源码根目录，默认值：./ |
| -o, --output | 生成文档输出位置，默认值：./doc |
| -t, --template | 生成文档使用的模版位置，默认值：%apidoc%\template\, %apidoc%为apidoc安装根目录 |
| -c, --config | 配置文件(apidoc.json)的所在位置，默认值：./ |
四、注意事项
1.没有参数说明时，apidoc会扫描当前目录以及所有子目录下.cs .dart .erl .go.java .js .php .py .rb .ts结尾的文件，生成api文档到当前目录下doc文件夹中;
2.apidoc -f后的正则表达式，标准格式".*\.java",eg:apidoc -f ".*\.java" ,必须使用双引号，并且单斜杠\,其他写法都会导致“No files found”;
3.@apiDefine定义的内容貌似只能作为name参数使用，这个局限太大，api中很多路径前半段都是相同的，想抽象出来一个都不行，以后如果修改，比较麻烦，不知道大家有没有什么高招可以解决
4.要写注解怎么能没有自动补全呢，java和php自动补全：Java Eclipse ,PHP Eclipse，官方文档说的很清楚了