在开发接口的过程中，需要向外发布相应的接口文档。开始的时候使用word来写文档，时间长了发现有几个问题。1) 编写不方便。每次新增借口的时候都要复制上一个接口，然后再进行修改，一些相同的部分无法复用，接口多了文档会变的很长，还经常需要调整格式。2) 发布不方便。文档更新时，需要发给需要的小伙伴。即使用git来进行管理，虽然拉取比较方便，但由于文件格式的问题，也不方便比较两次提交的差异。
由于有这些问题，决定寻找一种更优雅有效的方式来编写文档。经过比较，发现了apidoc,可以比较好的解决上面提到的问题。apidoc采用了一种类似写代码注释的方式来写文档，支持编写多种语言的文档。最后生成的文档以网页的形式发布，方便快捷，便于阅读。下面就来简单介绍一下怎么使用apidoc来写文档。
1.安装node
由于apidoc依赖node.js的包管理工具npm进行安装，所以安装apidoc之前要先安装node.js（npm会在安装node时顺带进行安装）。具体的安装教程可以参考这里。
2.安装apidoc
安装完了npm之后，就可以安装apidoc了。在命令行输入
npm install apidoc -g
就可以进行安装了。安装完成输入
apidoc -h
出现相关的提示帮助信息，说明安装成功了。
3 apidoc 常用注解介绍
apidoc是运用各个不同的注解来完成文档的写作的。学习apidoc，主要就是学习注解的用法。apidoc和命名行的命令很像，由一个注解关键字加一些选项构成。下面介绍一下apidoc主要的注解。
@api {method} path [title] 这是apidoc必需的注解，用来说明api的方法，访问路径和作用。
@apiParam [(group)] [{type}] [field=defaultValue] [description] 这个注解用来说明api请求参数的类型，大小和作用。
@apiSuccess [(group)] [{type}] field [description]
这个注解说明api返回参数的类型，大小和作用。
关于注解的详细用法可以访问官网，上面有详细的用法和示例。
4.编写apidoc文档
了解了关于注解的用法之后，就可以用注解来编写文档了。例如我们可以编写一个GetUser.java文件。里面的内容如下所示：
/**
* @api {get} /user/:id Request User information
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
5 生成apidoc文档
编写完成后，运行
apidoc -i apidocIn -o apidocOut
apidocIn表示GetUser.java文件的存放目录，apidocOut表示希望apidoc文档生成的目录。运行成功后，在输 出目录可以看见一堆生成的文件，其中index.html是我们需要的文档。在浏览器打开就可以看见效果了。效果如下图所示：
后面可以配置一下nginx，指定访问的路径映射到index.html，就可以让需要文档的小伙伴们访问了。