本文主要参考
- ApiDoc官方文档
最近项目开始接口测试，需要提供一份最新、最全的接口文档,也许你觉得没什么，但是如果我要求每个接口文档都要像下面的例子一样：
接口标题
接口描述
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多个...
最开始考虑肩扛人挑的方式梳理文档的我在整理了半天之后我就疯了，代码注释的不完整，需要人工核对实现逻辑，接口请求结果需要一个个跑请求来填写，这些本来在接口编写或者接口修改时就可以完成的内容，现在累加起来就像一个巨无霸工程。更可怕的是即使这次接口文档梳理完成了，等到若干个月之后，接口文档需要更新，然而你还需要这样一个个去核对哪些接口做了修改，更新文档！！！
面对这么痛的痛点，幸运的是，早就有大神为我们铺出了一条阳关大道—— apidoc
一、apidoc简介
apidoc是一个可以直接由源代码中滴注释生成api接口文档的自动化文档导出工具，并且支持目前流行的几乎所有格式的注释风格。该工具的源代码目前托管于github(https://github.com/apidoc/apidoc)，通过对该工具的使用，寡人目前总结的优点主要有以下几点：
① 文档生成依赖注释，对源代码几乎没有侵入；
② 规范化的注释利于协同开发，并且如果接口有变动，更新注释便等同于更新了接口文档；
③ 不同版本接口文档对比功能，方便对同一接口的不同版本进行比较查看。
说的这几点其实最主要的还是注释和文档的同步更新，相信几乎所有的开发者在写完代码后宁愿去更新注释也不愿意去更新接口文档。
二、自动化导出HTML接口文档
通过使用apidoc工具便可以直接导出HTML接口文档：
2.1 安装apidoc
apidoc通过npm安装，所以您需要先安装nodejs或者npm工具，安装完npm之后运行一下命令：
npm install apidoc -g
您也可以在docker环境中安装，此处不再赘述。
2.2 代码注释遵循apidoc风格
既然要使用apidoc导出文档，那自然要让apidoc认识你的注释，apidoc注释规范可以参考官方文档(http://apidocjs.com)，寡人也对官方的文档做了简要翻译注释(【ApiDoc】官方文档(翻译))，供大家参考。
2.3 运行apidoc 导出HTML文档
运行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 | 指定读取文件的文件名过滤正则表达式(可指定多个) 例如: apidoc -f ".*\\.js$" -f ".*\\.ts$" 意为只读取后缀名为js和ts的文件默认值: .clj .cls .coffee .cpp .cs .dart .erl .exs?.go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue |
| -e --exclude-filters | 指定不读取的文件名过滤正则表达式(可指定多个) 例如: apidoc -e ".*\\.js$" 意为不读取后缀名为js的文件默认: '' |
| -i, --input | 指定读取源文件的目录 例如： apidoc -i myapp/ 意为读取myapp/目录下面的源文件默认值: ./ |
| -o, --output | 指定输出文档的目录 例如： apidoc -o doc/ 意为输出文档到doc目录下默认值: ./doc/ |
| -t, --template | 指定输出的模板文件 例如: apidoc -t mytemplate/默认: path.join(__dirname, '../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即可在浏览器查看接口文档。
三、自动化导出Markdown接口文档
面对如此强大的apidoc工具，我一度以为可以通过修改输出模板文件来导出markdown文件，但通过查看当前版本(0.17.6)源代码，我发现apidoc在生成输出文件的时候仅仅是将模板文件拷贝到输出目录下，并没有像我想象的那样根据模板文件生成输出文档，apidoc所做的工作主要是通过读取源代码中的注释，解析生成一个api_data.json文件，这个文件里面包含了所有从注释中提取粗来的接口数据。所以接下来的工作便是根据这个api_data.json文件生成markdown文件即可。
幸运的是，GitHub上已经有好心人为我们做了这个工作。
3.1 安装apidoc-markdown
apidoc-markdown是一个根据apidoc输出文件直接生成markdown文件的工具。首先我们需要安装该工具：
npm install apidoc-markdown -g
3.2 导出Markdown文档
apidoc-markdown主要命令参数如下：
| 参数 | 描述 |
|---|---|
| -p, --path | 指定apidoc生成的文档目录 |
| -o, --output | 指定输出的markdown文件路径(包含文件名) 例如: apidoc-markdown -o output_dir/markdown_name.md |
| -t, --template | 指定生成markdown文件的模板文件(EJS模板文件) 默认: 使用工具自带的模板文件 |
通常情况下，我们需要允许下面这样的命令:
apidoc-markdown -p apidoc_dir -o doc/doc_markdown.md
这样我们便完成了接口文档从HTML到Markdown文件的转化。
3.3 添加自定义的markdown模板文件
由于该工具自带的markdown模板并不是非常完美，对于api_data.json文件中的字段并不是完全解析，所以你需要自己分析api_data.json中的数据接口，完善markdown模板文件。该文件是EJS模板文件，语法比较简单，有需要的童鞋可以自行Google，另外您也可以下载该工具的源代码，修改里面自带的模板文件也比较方便。
四、自动化导出PDF接口文档
既然markdown文件都有了，那么导出PDF文件不是更简单了。在这里，寡人推荐一个灰常好用的markdown离线编辑工具——Typora
Typora是一款离线轻量Markdown编辑器，该工具非常简洁、易用(目前处于测试阶段，可免费使用)。具体如何简单、易用在这里就不做赘述了，大家可以自行下载体验。其实最主要原因还是因为这个编辑器的导出PDF文件功能，该编辑器导出的pdf文件会根据markdown文件的目录生成pdf的导航目录，这一点对于文档文件来说忒重要了！！！
五、总结
好了，至此任务基本上完成了，以后麻麻再也不用担心我写接口文档啦！
注：文中如有任何错误，请各位批评指正！