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文档。

    参考