API接口文档解决方案

5.2.2 项目的根目录增加文件 apidoc.json
{ "name": "springboot-sample 接口文档", "version": "1.0.0", "description": "", "title": "springboot-sample", "url" : "https://demo.test.com"
3 apidoc 实施方案
1） 测试环境部署统一的 api 文档服务器，目录按项目划分,访问路径: http://docs.***.com/api/项目名/ 2） 开发人员按照 apidoc 的规则对接口写详细的注释 3） 提交代码后，Jenkins 执行 gradle apidocs 命令生成 html 文件，然后上传到服务器对应的目录中
2 调研结果
为了解决以上问题，调研了主流的三个工具，swagger2、spring rest docs、apidoc
基于以下原则对软件做了筛选： 1）不允许使用注解（annotation），对代码侵入性比较强， 排除 swagger2 2）不运行 java 程序就能生成文档，排除 spring rest docs 3）可以给前端提供 mock 数据
* @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":152412787500 0}} */
所以采用了 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
}
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
* @apiParam (请求参数) {type} field=defaultValue description
* @apiParamExample 请求参数示例
*
example
*
* @apiParam (请求体) {type} field description
* @apiParam (请求体) {type} field=defaultValue description
5）添加模板内容
6）Java 文件中输入 apidoc 使用
/**
* @apiVersion 1.0.0
* @api {method$END$} path title
* @apiGroup enName
* @apiName enName
*
* @apiParam (请求参数) {type} field description
} String apidocCmd = isWindows() ? 'apidoc.cmd' : 'apidoc' task apidocs(type: Exec, description: '执行生成 apidoc 文档操作') {
workingDir './' def docCommand = [apidocCmd, '-o', './build/apidocs'] commandLine docCommand }
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/
API 接口文档解决方案
1 调研背景
目前存在以下情况: 1）一般开发人员更新接口后，没有同时更新 rap，rap 上的接口定义普遍存在跟代码不一致的情况。 2）后端开发人员查看别人接口，很难很快地知道接口的作用，以及接口入参和返回结果中每个字段的含义。 3）rap 上的 mock 数据功能不是特别好用。
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()
* @apiParamExample 请求体示例
*
example
*
* @apiSuccess (响应参数) {type} field description
* @apiSuccess (响应参数) {type} field description
* @apiSuccessExample 响应示例
*
example
*/
5.2.4 本地执行 gradle apidocs，生成文档
Βιβλιοθήκη Baidu
5.2.5 其他：idea 注释模板使用
1）Settings-->editorLive Templates 新增模板
2）Abbreviation 设置为 apidoc
3）Context type 设置为 java:declaration
4）勾选 Reformat according to stype