阅读数:

如何快速生成api文档,并支持http访问

0

说明

我们经常会遇到这样的一个场景,api和文档往往是独立书写的,一般都是先设计好api文档然后交给开发实现,或者先写好api然后在利用conflunce等md工具
书写文档,耗时耗力,有时候还得费劲调整样式。今天我将分享一款神奇,在你写api的同时自动输出api文档,这个神器就是
apidoc,它的原理就是根据官方指定的格式定义接口方法说明,遍历指定文件,输出模版规定的文档。
支持java,javascript,C#,php,python,ruby等开发语言。
apidoc1
那么如何在现有项目基础上进行搭建实现呢?让我们以node项目为例走起,
项目目录结构如下:
apidoc2

实现

  • 安装apidoc
1
npm install apidoc -g
  • 编写apicode.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"name": "轻应用api文档",
"version": "0.0.0",
"description": "轻应用api文档",
"title": "轻应用api文档",
"url" : "http://localhost:8001/api/",
"order": [
"GetUser",
"PostUser"
],
"template": {
"withCompare": true,
"withGenerator": true
},
"header": {
"title": "回到底部",
"filename": "template/header.md"
},
"footer": {
"title": "回到顶部",
"filename": "template/footer.md"
}
}

说明:
| 参数 | 说明 |
| ——– | —– |
| url | api访问根地址 |
| order | 排序,先get后post |
| template | 生成模版,withCompare,支持版本比较,withGenerator 是否显示apidoc官方支持,false不显示 |
| header | 头部模版 |
| footer | 尾部模版 |

  • api接口方法定义

apidoc3

说明:可能你会说有点麻烦,但是我要说很有必要,因为合格优秀的代码也应该类似说明,声明参数类型,含义已经返回类型,只不过这次
我们是以apidoc官方要求的来做这件事,一箭双雕,既明晰的代码熟悉规则又为api的生成做了铺垫,具体参数说明详见官方文档

*设置模版
-t mytemplate 该命令用来指定api生成用的模版,可以默认,但是如果你想定制,可以下载模版源码
放在项目目录下,并作自定义比如样式调整等个性化需要

  • 执行命令
1
apidoc -i api/routes/ -o api/public/apidoc/ -t mytemplate/

说明: -i 指定被自动生成api的路径
-o 指定文档输出的路径
-t 指定模版,可以不选这个参数,用默认模版

  • 输出

最终会在api/public文件夹下生成一个apidoc的文件夹,这就是我们的api文档,直接访问 http://localhost:8001/apidoc
可以看到如下结果
apidoc4

  • 快速命令
    每次执行apidoc -i api/routes/ -o api/public/apidoc/ -t mytemplate/ 很麻烦
    我们可以在package.json script中加上一句,这样我们就可以用npm run mkapi来快速生成了

apidoc5

最后

是不是很方便呢,一老永逸,适合后台开发的同学,可以试试


0
赏点咖啡钱^.^