丢掉word，用apidoc来写文档

在开发接口的过程中，需要向外发布相应的接口文档。开始的时候使用word来写文档，时间长了发现有几个问题。

• 编写不方便。每次新增借口的时候都要复制上一个接口，然后再进行修改，一些相同的部分无法复用，接口多了文档会变的很长，还经常需要调整格式。
• 发布不方便。文档更新时，需要发给需要的小伙伴。即使用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，就可以让需要文档的小伙伴们访问了。