apidoc接口文档自动生成工具

使用背景 :

由于后端接口开发好，提供接口文档供前端人员调用；由于某种原因，修改了接口，文档没有及时更新，导致后续交接或联调时接口文档不匹配；使用apidoc文档自动生成工具，解决这一问题。

方案介绍 :

apidoc是基于node语言写的接口文档生成工具。

特点：

• 适用于多种语言，包括并不限于 java、node、php、c#等语言

• 与业务代码无耦合，直接修改注释的格式即可

• 接口文档是HTML页面，简洁明了

git地址：

https://github.com/apidoc/apidoc

使用步骤 :

1）环境安装

• 安装node运行环境和npm第三方包

• 安装apidoc模块，执行命令 npm install apidoc -g

2）项目接入apidoc（举例 基于 javaweb 微信公众号项目）

安装好环境之后，在项目的根目录创建文件apidoc.json

打开apidoc.json进行编辑

对应的页面效果

3）代码注释说明

定义一个全局属性，变量名在整个项目中不能重复（一处定义，四处引用） @apiDefine 变量名 变量说明 详细说明

示例： @apiDefine statistic 统计模块 微信管理员查看相关指标，粉丝分布情况，场景二维码创建情况，自定义菜单使用情况等等

定义其他全局变量

4）接口代码 注释及详情示例，括号里面是说明

5）生成接口文档

使用技巧

后端项目加入git管理，项目使用自动构建工具(如Jenkins); 

当开发人员提交代码到git里，Jenkins会 监听是否有代码提交，一旦发现有代码发送变化，则执行对应的shell脚本.。

我们在shell脚本里面执行apidoc构建命令，并把构建好的文档传输到统一的文档服务器，配置域名，项目组的人就能访问到最新的文档。

关于apidoc详情，请参考资料 相关资料： 

英文官网：http://apidocjs.com/#install 

长按图片识别图中二维码(或搜索微信公众号FrontEndStory)关注“前端那些事儿”，带你探索前端的奥秘。