apidoc

下面内容以项目insurance-2a-broker为例

1. 项目根目录增加文件 .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'

2. 项目根目录增加文件apidoc.json

   { "name": "insurance-2a-broker接口文档", "version": "1.0.0", "description": "", "title": "insurance-2a-broker", "url": "https://broker-2a-api.winbaoxian.cn" }

3. 使用工具生成注释

   apidoc注释生成工具

4. 将注释复制粘贴到代码中，修改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"}} */

5. 提交代码，等Jenkins执行完，访问文档，访问路径格式：http://docs.*.cn/api/{项目名}

6. 前端数据mock，mock地址格式：https://apidoc-mock.*.cn/{项目名}/{接口地址}，接口的请求方式需要与文档一致

servicedoc

下面内容以项目insurance-2a-broker为例

1. 项目根目录增加文件 .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'

2. 项目根目录增加文件servicedoc.json

   {

   "name": "insurance-2a-broker接口文档",
   "version": "1.0.0",
   "description": "",
   "title": "insurance-2a-broker"
   }

3. 使用工具生成注释

   servicedoc注释生成工具

4. 将注释复制粘贴到代码中，修改字段的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 结果示例 */

5. 提交代码，等Jenkins执行完，访问文档，访问路径格式：http://docs.*.cn/service/{项目名}