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.csdn.net/forezp/article/details/71023510

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

 springboot集成apidoc     http://blog.csdn.net/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.gradle.internal.os.OperatingSystem.current().isWindows()
3. }
4. String apidocCmd = isWindows() ? 'apidoc.cmd' : 'apidoc'
5. task apidocs(type: Exec, description: '执行生成apidoc文档操作') {
6. workingDir './'
7. def docCommand = [apidocCmd, '-o', './build/apidocs']
8. commandLine docCommand
9. }

5.2.2项目的根目录增加文件apidoc.json

 

1. {
2. "name": "springboot-sample接口文档",
3. "version": "1.0.0",
4. "description": "",
5. "title": "springboot-sample",
6. "url" : "https://demo.test.com"
7. }

 

 

5.2.3 Controller根据apidoc的规范增加注释（ http://apidocjs.com/）

 

1. /**
2. * @apiVersion 1.0.0
3. * @api {GET} /group/front/getOutlinePaySuccessInfo 获取支付成功数据
4. * @apiGroup TransferAccount
5. * @apiName getOutlinePaySuccessInfo
6. * @apiParam (请求参数) {String} orderID 订单号
7. * @apiParam (请求参数) {String} partnerCode 渠道code
8. * @apiParam (请求参数) {String} sign 签名
9. * @apiParamExample 请求参数示例
10. * ?orderID=G0000168752925895356416&partnerCode=wyxx&sign=064d8cc51ed0957839e62f6684a4fe5c
11. * @apiSuccess (响应参数) {String} accountName 收款人
12. * @apiSuccess (响应参数) {Number} insuredNum 被保人数量
13. * @apiSuccess (响应参数) {String} returnUrl 跳转地址（可能为空）
14. * @apiSuccess (响应参数) {Number} validStartDate 开始时间
15. * @apiSuccess (响应参数) {Number} validEndDate 截止时间
16. * @apiSuccessExample 响应示例
17. * {"code":200,"msg":"成功","data":{"groupName":"微易测试","insuredNum":5,"returnUrl":"http://www.baidu.com","validStartDate":1524127875000,"validEndDate":1524127875000}}
18. */

 

5.2.4 本地执行gradle apidocs，生成文档

5.2.5  其他：idea注释模板使用

1）Settings-->editorLive Templates 新增模板

2）Abbreviation设置为apidoc

3）Context type设置为java:declaration

4）勾选Reformat according to stype

5）添加模板内容

6）Java文件中输入apidoc使用

 

1. /**
2. * @apiVersion 1.0.0
3. * @api {method$END$} path title
4. * @apiGroup name
5. * @apiName name
6. *
7. * @apiParam (请求参数) {type} field description
8. * @apiParam (请求参数) {type} field=defaultValue description
9. * @apiParamExample 请求参数示例
10. * example
11. *
12. * @apiParam (请求体) {type} field description
13. * @apiParam (请求体) {type} field=defaultValue description
14. * @apiParamExample 请求体示例
15. * example
16. *
17. * @apiSuccess (响应参数) {type} field description
18. * @apiSuccess (响应参数) {type} field description
19. * @apiSuccessExample 响应示例
20. * example
21. *
22. */

 

文章出自：http://blog.suiyiwen.com/post/4