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