在开发接口的过程中，需要向外发布相应的接口文档。开始的时候使用word来写文档，时间长了发现有几个问题。
1. 编写不方便。每次新增借口的时候都要复制上一个接口，然后再进行修改，一些相同的部分无法复用，接口多了文档会变的很长，还经常需要调整格式。
2. 发布不方便。文档更新时，需要发给需要的小伙伴。即使用git来进行管理，虽然拉取比较方便，但由于文件格式的问题，也不方便比较两次提交的差异。
由于有这些问题，决定寻找一种更优雅有效的方式来编写文档。经过比较，发现了apidoc,可以比较好的解决上面提到的问题。apidoc采用了一种类似写代码注释的方式来写文档，支持编写多种语言的文档。最后生成的文档以网页的形式发布，方便快捷，便于阅读。下面就来简单介绍一下怎么使用apidoc来写文档。
安装
1. 由于apidoc依赖node.js的包管理工具npm进行安装，所以安装apidoc之前要先安装node.js（npm会在安装node时顺带进行安装）。具体的安装教程可以参考这里。
2. 安装完了npm之后，就可以安装apidoc了。在命令行输入
npm install apidoc -g
就可以进行安装了。安装完成输入
apidoc -h
出现相关的提示帮助信息，说明安装成功了。
使用
1. 在需要生成文档的地方新建一个apidoc.json文件,配置如下
{
"name": "appleFarm",//文档项目名
"title": "appleFarmAPI",//html标题
"description":"appleFarmAPI接口文档",//文档描述
"url" : "https://farm.05948166.com",//公共接口地址
"version": "0.1.0"//文档版本
}
2. 在新建apidoc.json的地方打开命令行输入apidoc即可在本目录下生成doc目录直接访问即可
语法
举个栗子
/**
* @api {get} /articles/:id 根据单个id获取文章信息
* @apiName 根据id获取文章信息
* @apiGroup Articles
*
* @apiParam (params) {String} id 文章id
*
* @apiSuccess {Array} article 返回相应id的文章信息
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "tile": "文章标题2",
* "date": 1483941498230,
* "author": "classlfz",
* "content": "文章的详细内容"
* }
*
* @apiError (Error 4xx) 404 对应id的文章信息不存在
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 对应id的文章信息不存在
* {
* "error": err
* }
*/
详细介绍
@api
@api一般是必须编写的（除非你是用了@apiDefine），不然apidoc编译器会忽略这段注释。
/**
* @api {method} path [title]
*/
| 参数 | 描述 |
|---|---|
| method | 请求的方法名称：如GET、POST等等 |
| path | 请求路径(只需要拼写apidoc.json中配置地址的后面部分即可) |
| title(可选) | 一个简短的标题（用于导航跟文档标题） |
@apiGroup
定于api归属的组名，生成的文档会把该api注释归类到该值对应的api组上。
/** * @apiGroup name */
| 参数 | 描述 |
|---|---|
| name | 归属组名称 |
@apiName
@apiName用于定义API文档的一个实例，并用作实例名称 。
/** * @apiName name */
| 参数 | 描述 |
|---|---|
| name | 实例名称 |
@apiParam
@apiParam用于编写API的参数以及参数的解释。
/**
* @apiParam [(group)] [{type}] [field=defaultValue] [description]
*/
| 参数 | 描述 |
|---|---|
| (group) 可选 | 参数归属组名，不填写组名，则默认设为Paramter |
| {type} 可选 | 参数数据类型，如{String}、{Number}、{Array}等等 |
| {type{size}} 可选 | 变量的大小信息 {String{..5}}参数类型为一个字符不超过5的字符串；{String{2..5}}参数为一个字符在2到5之间的字符串； |
| {type=allowedValues} 可选 | 参数允许值 {string=”small”,”huge”}参数只能接受small或者huge的字符串 |
| field 可选 | 参数名称 |
| =defaultValue | 参数默认值 |
| description(可选) | 描述 |
@apiParamExample
@apiParamExample参数举例
/**
* @apiParamExample [{type}] [title]
* example
*/
| 参数 | 描述 |
|---|---|
| {type} 可选 | 请求数据结构 |
| title 可选 | 例子的一个简短的标题 |
| example | 例子的详细信息，可多个例子并存 |
@apiSuccess
请求成功后的返回字段参数
/**
* @apiSuccessExample [{type}] [title] example
*/
| 参数 | 描述 |
|---|---|
| (group) 可选 | 参数归属组名，不填写组名，则默认设为Success 200 |
| {type} 可选 | 返回的数据类型，如{String}、{Number}等等 |
| field | 返回的标示符（返回成功的状态码） |
| description 可选 | 描述 |
@apiSuccessExample
请求成功后返回的字段参数例子
/**
* @apiSuccessExample [{type}] [title] example
*/
| 参数 | 描述 |
|---|---|
| {type} 可选 | 请求数据结构 |
| title 可选 | 例子的一个简短的标题 |
| example | 例子的详细信息，可多个例子并存 |
@apiError & @apiErrorExample
这个的用法跟@apiSuccess、@apiSuccessExample的用法相类似。
来源：https://www.cnblogs.com/jiangxiaobo/p/8320916.html