4. GeekPipe-基于Drone的APIDOC实践和自动化生成

GeekPipe-基于Drone的APIDOC实践和自动化生成


  • APIDOC 简介

    随着移动客户端的流行，后端系统需开放越来越多的API来供客户端使用。API文档的编写和管理是一个挑战，随着API不断变化，文档必须及时更新，但编写文档也是个不小的负担。一个比较好的做法(Best Practice)，就是将文档放在代码里，开发人员编写代码时同时修改文档。然后通过工具从代码中抽出文档，并生成方便用户阅读的格式。此类工具早已存在，比如Java中的javadoc。这里我们要介绍一个非常轻量级的，适用于几乎所有流行语言的，针对Restful API的文档自动生成工具－apiDoc。

    APIDOC 是一个基于 nodejs 的 API 文档生成工具，从代码注释中提取特定格式的内容，生成 API 文档。目前支持的语言有：C#、C/C 、D、Erlang、Go、Groovy、Java、Javascript、Pascal/Delphi、Perl、PHP、Python、Rust、Ruby、Scala 和 Swift。

    其特点如下：

    • 跨平台，linux、windows、macOS 等都支持。
    • 支持语言广泛。
    • 支持文档版本管理。
    • 支持多个不同语言的多个项目生成一份文档。
    • 输出模板可自定义。

    举个例子

    以 Django 为例，在 views 函数中写注释

    def myview(request, id):  
"""     
    @api {GET} ci/app/:id/ 获取应用详情  
    @apiVersion 1.0.0  
    @apiDescription 获取应用详情  
    @apiName getAppDetail  
    @apiGroup Application  
    @apiSuccessExample  请求成功  
    HTTP/1.1 200 OK  
    {  
        "result": true,  
        "data": [],  
        "code": 0,  
        "message": u'成功说明'  
    }  
    @apiSuccess {Boolean} result true  
    @apiSuccess {Array} data  数据列表  
    @apiSuccess {Number} code 0  
    @apiSuccess {String} message 说明         
    """

    生成的 API 文档

    APIDOC语法规范

    APIDOC 是通过抽取代码注释，根据关键字语法生成 API 文档。所以，如果想生成理想的 API 文档，一定要遵循 apidoc 的相关关键字语法。下面是一个关键字语法的 list，{ }表示需要替换的变量，[ ]表示可选参数：

    @api {method} path [title]。
只有使用@api 标注的注释块才会在解析之后生成文档，title 会被解析为导航菜单(@apiGroup) 下的小菜单
method 可以有空格，如{POST GET}
@apiGroup name。
分组名称，被解析为导航栏菜单
@apiName name。
接口名称，在同一个@apiGroup 下，名称相同的@api 通过@apiVersion 区分，否者后面@api 会覆盖前面定义的@api
@apiDescription text。
接口描述，支持 html 语法
@apiVersion verison。
接口版本，major.minor.patch 的形式
@apiIgnore [hint]。
apidoc 会忽略使用@apiIgnore 标注的接口，hint 为描述
@apiSampleRequest url。
接口测试地址以供测试，发送请求时，@api method 必须为 POST/GET 等其中一种
@apiDefine name [title] [description]。
定义一个注释块(不包含@api)，配合@apiUse 使用可以引入注释块
在@apiDefine 内部不可以使用@apiUse
@apiUse name。
引入一个@apiDefine 的注释块
@apiParam [(group)] [{type}] [field=defaultValue] [description]。请求参数
@apiHeader [(group)] [{type}] [field=defaultValue] [description]。头部参数
@apiError [(group)] [{type}] field [description]。响应错误时参数
@apiSuccess [(group)] [{type}] field [description]。成功时参数，
group 表示参数的分组，type 表示类型(不能有空格)，入参可以定义默认值(不能有空格)
@apiParamExample [{type}] [title] example。参数请求用例
@apiHeaderExample [{type}] [title] example。头部请求用例
@apiErrorExample [{type}] [title] example。错误请求用例
@apiSuccessExample [{type}] [title] example。成功请求用例
type 表示的是 example 的语言类型， example 内容会被直接解析显示。
@apiPermission name。
name 必须独一无二，描述@api 的访问权限，如 admin/anyone

    基于Drone的自动化更新API文档

    添加代码扫描路径

    编辑doc仓库里的脚本文件gendoc.sh，添加代码仓库路径，如下所述：

    如果有多个仓库，则另起一行添加路径即可。

    配置.drone.yml文件

      gen_api_doc:
    image: plugins/downstream
    server: https://drone.finogeeks-test.club
    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXh0IjoieWFuZ3RhbyIsInR5cGUiOiJ1c2VyIn0.0IiIB0dIq6ZF_pKuhO4-Z8-8vGiUmmb2g-0Tr-sN3Xs
    fork: true
    repositories:
      - xxx/doc
    when:
      status: [success]
      event: [tag]

    至此，如果代码提交并成功打tag的时候，APIDOC便会自动扫描代码中的注释代码，更新API文档。

    参考

    0