API接口文档生成方案调研
  • 首页 > >
  • 作者:Saber
  • 2018年5月29日 12:19 星期二
  • 浏览:43 次
  • 字号:    
  • 评论:0 条   编辑
  • 时间:2018-5-29 12:19   浏览:43  


    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
    *
    */


     您阅读这篇文章共花了: 
    返回顶部 返回首页
  • 文章:3 篇
  • 评论:0 条
  • 微语:0 条
  • 友链:2 个
  • 分类:0 个
  • 标签:6 个
  • 作者:1 人
  • 建站日期: