丢掉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,就可以让需要文档的小伙伴们访问了。

你可能感兴趣的:(丢掉word,用apidoc来写文档)