apidoc&servicedoc实践

作者:Saber 分类: 原创 发布于:2018-10-25 10:37 ė62次浏览 60条评论

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/{项目名}

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

发表评论

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


Ɣ回顶部