API接口文档生成方案调研

1调研背景

目前存在以下情况:

1）一般开发人员更新接口后，没有同时更新rap，rap上的接口定义普遍存在跟代码不一致的情况。

2）后端开发人员查看别人接口，很难很快地知道接口的作用，以及接口入参和返回结果中每个字段的含义。

3）rap上的mock数据功能不是特别好用。

2 调研结果

为了解决以上问题，调研了主流的三个工具，swagger2、spring rest docs、apidoc

 

基于以下原则对软件做了筛选：

1）不允许使用注解（annotation），对代码侵入性比较强， 排除swagger2

2）不运行java程序就能生成文档，排除spring rest docs

3）可以给前端提供mock数据

 

所以采用了apidoc

 

参考文章：

 用spring Restdocs创建API文档   http://blog.youkuaiyun.com/forezp/article/details/71023510

 springboot集成swagger2，构建优雅的 Restful API http://blog.youkuaiyun.com/forezp/article/details/71023536

 springboot集成apidoc     http://blog.youkuaiyun.com/forezp/article/details/71023579

3 apidoc实施方案：

1） 测试环境部署统一的api文档服务器，目录按项目划分,访问路径: http://docs. ***.com/api/项目名/

2） 开发人员按照apidoc的规则对接口写详细的注释

3） 提交代码后，Jenkins执行gradle apidocs命令生成html文件，然后上传到服务器对应的目录中

4 项目参考案例

项目：git@git.***.com:wy-serverside/insurance-2b-group.git

文档：http://docs. ***.cn/api/insurance-2b-group/

Jenkins任务：test_insurance_2b_group

apidoc便捷生成工具：http://tool.suiyiwen.com/apidoc/

 

5 后端开发本地环境配置

5.1 Apidoc安装

首先需安装nodejs，然后安装apidoc(执行npm install apidoc –g)

5.2 项目配置

5.2.1 gradle项目的配置文件build.gradle增加配置

 

1. def isWindows() {
2. return org.