API接口文档生成方案调研

作者:Saber 分类: 方案调研 发布于:2018-5-29 12:19 ė346次浏览 60条评论


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增加配置


def isWindows() {
   return org.gradle.internal.os.OperatingSystem.current().isWindows()
}
String apidocCmd = isWindows() ? 'apidoc.cmd' : 'apidoc'
task apidocs(type: Exec, description: '执行生成apidoc文档操作') {
   workingDir './'
   def docCommand = [apidocCmd, '-o', './build/apidocs']
   commandLine docCommand
}

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

{
 "name": "springboot-sample接口文档",
 "version": "1.0.0",
 "description": "",
 "title": "springboot-sample",
 "url" : "https://demo.test.com"
}


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


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


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使用


/**
* @apiVersion 1.0.0
* @api {method$END$} path title
* @apiGroup name
* @apiName name
*
* @apiParam (请求参数) {type} field description
* @apiParam (请求参数) {type} field=defaultValue description
* @apiParamExample 请求参数示例
*             example
*
* @apiParam (请求体) {type} field description
* @apiParam (请求体) {type} field=defaultValue description
* @apiParamExample 请求体示例
*             example
*
* @apiSuccess (响应参数) {type} field description
* @apiSuccess (响应参数) {type} field description
* @apiSuccessExample 响应示例
*             example
*
*/


本文出自 轩的博客,转载时请注明出处及相应链接。

发表评论

电子邮件地址不会被公开。必填项已用*标注


Ɣ回顶部