apidoc&servicedoc实践
apidoc
下面内容以项目insurance-2a-broker为例
-
项目根目录增加文件 .gitlab-ci.yml,提交代码时触发Jenkins任务
trigger_build_doc: stage: deploy only: - develop script: - curl -X POST http://192.168.180.192/jenkins/job/bxs-apidoc/buildWithParameters --user USERNAME:110e0732fde118c802cb616637fd47278d -d 'projectName=insurance-2a-broker'
-
项目根目录增加文件apidoc.json
{
"name": "insurance-2a-broker接口文档", "version": "1.0.0", "description": "", "title": "insurance-2a-broker", "url": "https://broker-2a-api.winbaoxian.cn" }
-
使用工具生成注释
-
将注释复制粘贴到代码中,修改apiGroup、apiName、字段的description,例:
/** @apiVersion 1.0.0 @api {POST} /guaranteeCalc/submit 提交保障测算数据 @apiGroup guaranteeCalc @apiName submit @apiParam (请求体) {Number} age 年龄 @apiParam (请求体) {Object} car 车信息 @apiParam (请求体) {Number} car.leftMortgage 剩余贷款,单位:元 @apiParam (请求体) {Boolean} car.mortgageFlag 是否贷款 @apiParam (请求体) {Boolean} car.ownFlag 是否有车 @apiParam (请求体) {Array} familyMemberList 家庭成员信息 @apiParam (请求体) {Number} familyMemberList.age 年龄 @apiParam (请求体) {Number} familyMemberList.sex 性别,1:男 2:女 @apiParam (请求体) {String} familyMemberList.title 成员title, mate:配偶 firstChild:第一个孩子 secondChild: 第二个孩子 @apiParam (请求体) {Object} house 房产信息 @apiParam (请求体) {Number} house.leftMortgage 剩余贷款,单位:元 @apiParam (请求体) {Boolean} house.mortgageFlag 是否贷款 @apiParam (请求体) {Boolean} house.ownFlag 是否有房 @apiParam (请求体) {Number} income 家庭年收入, 单位:元 @apiParam (请求体) {Number} outgo 家庭年支出, 单位:元 @apiParam (请求体) {Number} otherDebt 其他负债, 单位:元 @apiParam (请求体) {Number} retireOutgoPerMonth 退休阶段预计每月支出,单位:元 @apiParam (请求体) {Array} riskList 已有保障信息 @apiParam (请求体) {Number} riskList.amount 保额,单位:元 @apiParam (请求体) {String} riskList.riskCode 险种code,ACCIDENT:意外险,MAJOR_DISEASE:重疾险 LIFE:人寿险 EDUCATION:教育金 ANNUITIES:养老金 @apiParam (请求体) {Number} sex 性别,1:男 2:女 @apiParamExample 请求体示例 {"age":29,"car":{"leftMortgage":70000,"mortgageFlag":true,"ownFlag":true},"familyMemberList":[{"age":32,"sex":2,"title":"mate"},{"age":12,"sex":1,"title":"firstChild"},{"age":8,"sex":2,"title":"secondChild"}],"house":{"leftMortgage":500000,"mortgageFlag":true,"ownFlag":true},"income":40000,"outgo":20000,"retireOutgoPerMonth":8078,"otherDebt":20000,"riskList":[{"amount":4000,"riskCode":"ACCIDENT"},{"amount":70000,"riskCode":"MAJOR_DISEASE"},{"amount":20000,"riskCode":"LIFE"},{"amount":10000,"riskCode":"EDUCATION"}],"sex":1} @apiSuccess (响应参数) {String} resultUuid 测算结果UUID @apiSuccessExample 响应示例 {"code":200,"data":{"resultUuid":"odfdsjlxxxaa123"}} */
-
提交代码,等Jenkins执行完,访问文档,访问路径格式:http://docs.*.cn/api/{项目名}
-
前端数据mock,mock地址格式:https://apidoc-mock.*.cn/{项目名}/{接口地址},接口的请求方式需要与文档一致
servicedoc
下面内容以项目insurance-2a-broker为例
-
项目根目录增加文件 .gitlab-ci.yml,提交代码时触发Jenkins任务
trigger_build_doc: stage: deploy only: - develop script: - curl -X POST http://192.168.180.192/jenkins/job/bxs-servicedoc/buildWithParameters --user USERNAME:110e0732fde118c802cb616637fd47278d -d 'projectName=insurance-2a-broker'
-
项目根目录增加文件servicedoc.json
{"name": "insurance-2a-broker接口文档", "version": "1.0.0", "description": "", "title": "insurance-2a-broker" }
-
使用工具生成注释
-
将注释复制粘贴到代码中,修改字段的description,例:
/** @serviceVersion 1.0.0 @serviceAuthor 董轩梁 @serviceGroup IBrokerUserService @serviceName getTopBrokerUserInfo @service 查询交服总信息 TopBrokerUserInfoDTO getTopBrokerUserInfo(String mobile) @serviceParam (mobile) {String} mobile 手机号 @serviceParamExample mobile 15957148997 @serviceResult (结果) {Number} userRank 该手机号用户层级 1:交服总 2:主管 3:业务员 @serviceResult (结果) {String} jfzMobile 交服总手机号 @serviceResult (结果) {String} jfzName 交服总姓名 @serviceResultExample 结果示例 */
-
提交代码,等Jenkins执行完,访问文档,访问路径格式:http://docs.*.cn/service/{项目名}
本文出自 轩的博客,转载时请注明出处及相应链接。
发表评论