本文主要参考
最近项目开始接口测试,需要提供一份最新、最全的接口文档, 也许你觉得没什么,但是如果我要求每个接口文档都要像下面的例子一样:
接口描述
- POST / request_api_url
请求头参数列表:
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
header_param_1 | string | yes | 参数描述 |
header_param_2 | string | yes | 参数描述 |
请求体参数列表:
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
body_param_1 | string | yes | 参数描述 |
body_param_2 | string | yes | 参数描述 默认值: test |
body_param_3 | int | no | 参数描述 默认值: 1 可选值: 0,1, |
请求示例:
- curl -i -X POST -d body_param_1=value1&body_param_2=value2 http://localhost/request_api_url
请求参数示例 1:
- {
- "body_param_1": "value1",
- }
请求参数示例 2:
- {
- "body_param_1": "value1",
- "body_param_2": "value2",
- "body_param_3": 1
- }
请求成功示例 1:
- {
- "status": "success",
- "data": {
- "key1": "value1",
- }
- }
请求成功示例 2:
- {
- "status": "success",
- "data": {
- "key1": "value1",
- "key2": "value2",
- "key3": "key3",
- "update_time": 1509431405,
- "create_time": 1509431405
- }
- }
请求错误示例 1:
- {
- "status": "failure",
- "error_message": {
- "error_code":403
- ...
- }
- }
请求错误示例 2:
- {
- "status": "failure",
- "error_message": {
- "error_code":404
- ...
- }
- }
怎么样?小伙子,你有没有感受到一丝丝的繁琐?
如果我还告诉你我不仅需要 PDF 版的,我还需要 Markdown 版的,还可能需要 html 版的,怎么样?小伙子,你有没有感受到一丝丝的绝望?
如果我还告诉你现在需要整理的接口有 160 多个...
最开始考虑肩扛人挑的方式梳理文档的我在整理了半天之后我就疯了,代码注释的不完整,需要人工核对实现逻辑,接口请求结果需要一个个跑请求来填写,这些本来在接口编写或者接口修改时就可以完成的内容,现在累加起来就像一个巨无霸工程。更可怕的是即使这次接口文档梳理完成了,等到若干个月之后,接口文档需要更新,然而你还需要这样一个个去核对哪些接口做了修改,更新文档!!!
面对这么痛的痛点,幸运的是,早就有大神为我们铺出了一条阳关大道——
apidocapidoc 是一个可以直接由源代码中滴注释生成 api 接口文档的自动化文档导出工具,并且支持目前流行的几乎所有格式的注释风格。该工具的源代码目前托管于 github( https://github.com/apidoc/apidoc ),通过对该工具的使用,寡人目前总结的优点主要有以下几点:
① 文档生成依赖注释,对源代码几乎没有侵入;
② 规范化的注释利于协同开发,并且如果接口有变动,更新注释便等同于更新了接口文档;
③ 不同版本接口文档对比功能,方便对同一接口的不同版本进行比较查看。
说的这几点其实最主要的还是注释和文档的同步更新,相信几乎所有的开发者在写完代码后宁愿去更新注释也不愿意去更新接口文档。
通过使用 apidoc 工具便可以直接导出 HTML 接口文档:
apidoc 通过 npm 安装,所以您需要先安装 nodejs 或者 npm 工具,安装完 npm 之后运行一下命令:
- npm install apidoc - g
您也可以在 docker 环境中安装,此处不再赘述。
既然要使用 apidoc 导出文档,那自然要让 apidoc 认识你的注释,apidoc 注释规范可以参考官方文档 ( http://apidocjs.com ),寡人也对官方的文档做了简要翻译注释 ( 【ApiDoc】官方文档 (翻译) ),供大家参考。
运行 apidoc 前需要先添加一个配置文件 apidoc.json, 该配置文件的内容官方文档里有介绍,大致如下:
- {
- "name": "接口名称",
- "version": "0.1.0",
- "description": "Api接口文档",
- "url": "http://qa.api.test.com/",
- "sampleUrl": "http://qa.api.test.com/",
- "template": {
- "withCompare": true,
- "withGenerator": true
- }
- }
apidoc 主要命令参数如下:
参数 | 描述 |
---|---|
-f --file-filters | 指定读取文件的文件名过滤正则表达式 (可指定多个) 例如: 意为只读取后缀名为 js 和 ts 的文件默认值:
|
-e --exclude-filters | 指定不读取的文件名过滤正则表达式 (可指定多个) 例如: 意为不读取后缀名为 js 的文件默认:'' |
-i, --input | 指定读取源文件的目录 例如:apidoc -i myapp/ 意为读取 myapp / 目录下面的源文件 默认值:./ |
-o, --output | 指定输出文档的目录 例如:apidoc -o doc/ 意为输出文档到 doc 目录下 默认值:./doc/ |
-t, --template | 指定输出的模板文件 例如:
默认:
|
-c, --config | 指定包含配置文件 (apidoc.json) 的目录 例如: apidoc -c config/ 默认:./ |
-p, --private | 输出的文档中是否包含私有 api 例如: apidoc -p true 默认: false |
-v, --verbose | 是否输出详细的 debug 信息 例如: apidoc -v true 默认: false |
-h, --help | 查看帮助文档 |
通常情况下只需要指定源文件目录、输出文件目录、配置文件目录即可:
- apidoc - i source_dir / -c config_dir / -o output_dir /
运行完成后,您便可以在 output_dir 目录下看到生成的 html 文件,点击 index.html 即可在浏览器查看接口文档。
面对如此强大的 apidoc 工具,我一度以为可以通过修改输出模板文件来导出 markdown 文件,但通过查看当前版本 (0.17.6) 源代码,我发现 apidoc 在生成输出文件的时候仅仅是将模板文件拷贝到输出目录下,并没有像我想象的那样根据模板文件生成输出文档,apidoc 所做的工作主要是通过读取源代码中的注释,解析生成一个 api_data.json 文件,这个文件里面包含了所有从注释中提取粗来的接口数据。所以接下来的工作便是根据这个 api_data.json 文件生成 markdown 文件即可。
幸运的是,GitHub 上已经有好心人为我们做了这个工作。
apidoc-markdown 是一个根据 apidoc 输出文件直接生成 markdown 文件的工具。首先我们需要安装该工具:
- npm install apidoc - markdown - g
apidoc-markdown 主要命令参数如下:
参数 | 描述 |
---|---|
-p, --path | 指定 apidoc 生成的文档目录 |
-o, --output | 指定输出的 markdown 文件路径 (包含文件名) 例如:
|
-t, --template | 指定生成 markdown 文件的模板文件 (EJS 模板文件) 默认:
|
通常情况下,我们需要允许下面这样的命令:
- apidoc - markdown - p apidoc_dir - o doc / doc_markdown.md
这样我们便完成了接口文档从 HTML 到 Markdown 文件的转化。
由于该工具自带的 markdown 模板并不是非常完美,对于 api_data.json 文件中的字段并不是完全解析,所以你需要自己分析 api_data.json 中的数据接口,完善 markdown 模板文件。该文件是 EJS 模板文件,语法比较简单,有需要的童鞋可以自行 Google,另外您也可以下载该工具的源代码,修改里面自带的模板文件也比较方便。
既然 markdown 文件都有了,那么导出 PDF 文件不是更简单了。在这里,寡人推荐一个灰常好用的 markdown 离线编辑工具—— Typora
Typora 是一款离线轻量 Markdown 编辑器,该工具非常简洁、易用 (目前处于测试阶段,可免费使用)。具体如何简单、易用在这里就不做赘述了,大家可以自行下载体验。其实最主要原因还是因为这个编辑器的导出 PDF 文件功能,该编辑器导出的 pdf 文件会根据 markdown 文件的目录生成 pdf 的导航目录,这一点对于文档文件来说忒重要了!!!
好了,至此任务基本上完成了,以后麻麻再也不用担心我写接口文档啦!
注:文中如有任何错误,请各位批评指正!
来源: http://www.jianshu.com/p/16ecf8a408e8