公众号关注 “GitHubDaily”
设为 “星标”,每天带你逛 GitHub!
大家好,我是小G。
前几天,粉丝群有小伙伴问,有啥好用的 API 文档工具推荐,无意间发现了 GitHub 上一款开源工具,这里马不停蹄的来给大家分享一下。
ShowDoc
一个非常适合团队的在线 API 文档开源工具,也支持用 docker
自建文档服务,不过为了方便演示,我直接用了平台在线服务。官网地址:
https://www.showdoc.com.cn/item/index
可以使用 markdown
语法来写 API 文档、数据字典文档、技术文档、在线 excel
文档。但像我这种资深的懒人程序员,其实更看重的是 showdoc
的自动化生成文档的特性,它可以从代码注释中自动生成 API 文档,或者搭配 RunApi
客户端(类似 postman 的 api 调试工具)一边调试接口、一边自动生成文档。
阮一峰老师在其最新的科技爱好者周刊中就推荐了这个文档工具。
下边从头演示下,来瞅瞅这玩意好用在哪?
![图片](https://static.doc-tr.net/mp-images/86/867649f10e2e909b8e83893f8b1e8b82.jpg?)
初识 ShowDoc
ShowDoc
新建项目可选常规的 API 文档、在线表格、或者单页文档(不支持目录分层),允许对项目文档设置访问密码,自定义域名,这里并不是真正意义上的 “域名”,只是在文档服务域名后加了一级目录,例如:
www.showdoc.com.cn/程序员内点事
![图片](https://static.doc-tr.net/mp-images/7d/7dcea3505c2d0c5c971d033987044fea.jpg?)
可以复制现有的项目,或直接导入 Postman
、swagger
的 API 接口配置 Json 文件。提供的开放 API 是自动化生成文档的关键,先记住有 api_key
、api_token
这两个属性,后边详细讲。
![图片](https://static.doc-tr.net/mp-images/2e/2e76f1fac3d9b8675e3a517e4966713c.jpg?)
进入项目后点击右上角 + 编辑文档,ShowDoc
预置了几种文档模板,也可以把自定义的文档存为模板;支持在线 Mock
服务,提前定义好接口的数据格式,先提供在线临时接口,这样就可以和前端同步开发,后边无缝切换;还有个简单的 API 在线测试功能。
![图片](https://static.doc-tr.net/mp-images/ca/ca19aae5fd7821e57deb1b12e27e8283.jpg?)
在线表格样式很简洁
![图片](https://static.doc-tr.net/mp-images/57/573a717166d6316b2327a7c06c194d62.jpg?)
导出文档有 word
、Markdown
两种格式。
![图片](https://static.doc-tr.net/mp-images/69/69dabb908f5ab815f0053e2fa39f7d87.jpg?)
支持版本控制,能看到每次修改的记录,回滚任意一个版本的修改。
![图片](https://static.doc-tr.net/mp-images/95/95b832d47f42d0c2a589462cfac1708c.jpg?)
在向别人分享在线文档时,如果不想将整个 API 目录都暴漏,可以选择进行单页面分享。
看到这感觉 showdoc
很普通啊,好像没什么特别的地方,上边的这些文档都是需要我们手动书写的,比较繁琐不推荐这么搞,接下来咱们看看如何自动化生成文档。
自动生成文档
showdoc
有三种自动生成 API 文档的方式:
-
使用 Runapi 工具自动生成(推荐) -
使用程序代码注释自动生成 -
自动生成数据字典 -
自己写程序调用接口来生成
Runapi 工具
Runapi
是一个以接口为核心的开发测试工具(可以看做是 Postman
的精简版)。目前客户端支持 win
、mac
、linux
平台和在线版 ,包含接口测试、自动流程测试、Mock 数据、项目协作等功能。
单纯的 Runapi
和 Postman
相比优势并不大,而与 showdoc
配合使用效率比较显著,用 runapi
测试接口的同时它将自动生成 API 文档到 showdoc
,也可共用 showdoc
的团队管理机制实现多人协作。
Runapi
客户端可以创建带调试的 API 接口文档、或者 Markdown 格式的文档。
![图片](https://static.doc-tr.net/mp-images/e3/e37aaca186d405991e6a4cd2f5b28f64.jpg?)
比如我们新建个项目 “程序员内点事
”,分别建三个接口 “点在
”、“在看
”、“关注
”,紧接着快速生成参数和响应结果数据并保存。
![图片](https://static.doc-tr.net/mp-images/1a/1a8f37d97a8664c42b97df23bc721643.jpg?)
点击右上角的文档链接
设置访问密码,不填默认是公开的,复制文档链接在浏览器中打开,看到 API 接口文档已经生成。runapi 还有全局参数、环境隔离。其实 Postman
也支持这样的功能,不过毕竟不是国内产品,网络访问等方面很受限制。
![图片](https://static.doc-tr.net/mp-images/59/5931d7f3b131b22e26fd576a442fa865.jpg?)
还有一个比较好的地方,Runapi
支持接口执行前后的脚本,比如响应数据的断言测试,弹框显示都挺好用的。
![图片](https://static.doc-tr.net/mp-images/50/50c97c4a052042d68df8d4c95cf1e434.jpg?)
代码注释
把接口的信息写在注释里也可以自动生成文档到 showdoc
,但这种我并不太喜欢,主要是侵入性比较强,让代码的阅读性变的比较差,一坨坨看着很不爽。
/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户注册
* @description 用户注册的接口
* @method post
* @url https://www.showdoc.com.cn/home/user/login
* @param username 必选 string 用户名
* @param password 必选 string 密码
* @param name 可选 string 用户昵称
* @return {"error_code":0,"data":{"uid":"1","username":"12154545","name":"吴系挂","groupid":2,"reg_time":"1436864169","last_login_time":"0"}}
* @return_param groupid int 用户组id
* @return_param name string 用户昵称
* @remark 这里是备注信息
* @number 99
*/
public Object register(){
这种方式的实现也比较简单,还记得前边的提到的 api_key
、api_token
这两个属性嘛,现在派上用场了,下边我用 windows 环境演示。
首先本地要有 git 环境:
https://npm.taobao.org/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe
再下载 showdoc 官方提供的脚本
https://www.showdoc.cc/script/showdoc_api.sh
修改 showdoc_api.sh
,替换我们 api_key
和 api_token
变量值,URL 如果没搭建自己的文档服务不用改。
![图片](https://static.doc-tr.net/mp-images/e4/e4c60fd323f1d0fbcdca69b237f9eb8f.jpg?)
将 showdoc_api.sh
放在你的项目目录下,直接双击运行,脚本会自动递归扫描本目录和子目录的所有文本代码文件,并生成 API 文档。
![图片](https://static.doc-tr.net/mp-images/87/87acfe6868230af538a410228c79a277.jpg?)
showdoc_api.sh
生成的文档会放进你填写 api_token
的这个项目里。
![图片](https://static.doc-tr.net/mp-images/fb/fb49c5e9c7e241b470cf99b7f197001b.jpg?)
生成数据字典
如果我们想直接从数据库字典表生成数据字典文档,showdoc
也是支持的,先下载官方提供的脚本
wget https://www.showdoc.cc/script/showdoc_db.sh
修改脚本里的配置,数据库、api_key
、api_token
等信息,直接执行后数据库表结构信息同步到 showdoc
。
如下配置的变量名和解释
效果就是如下图这样,生成了数据表字典文档,在一些特定场景下还是很方便的。
![图片](https://static.doc-tr.net/mp-images/12/12bb1aafcb760763631e5b1a872c79a8.jpg?)
开放 API
showdoc
开放了文档编辑的 API,我们可以在代码中调用 API 创建、编辑文档。这样使用的场景就比较灵活了。
https://www.showdoc.cc/server/api/item/updateByApi
API 参数如下,文档内容,可传递 markdown 格式的文本或者 html 源码都可以。
![图片](https://static.doc-tr.net/mp-images/97/97f95ed760aed3e8af25331f85f433b2.jpg?)
测试一下接口组装必要的参数,用简易在线 API 调试工具发送
{
"api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
"api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
"page_title": "xiaofu",
"page_content": "nihao"
}
看到在
showdoc
对应的项目里已经创建了名字为 xiaofu
的文档。
说两句
前边说过 showdoc
现有的功能 postman
基本都支持,但 postman
功能过于繁杂不够简洁,加上网络条件等诸多限制,协同办公的效率并不高,而 Runapi
配合 showdoc
在某些场景下能够很大程度上提升我们开发交付的效率,所以能自动生成的绝对不手写!
再怎么 BB 吹嘘都是苍白的,好不好用,适不适合自己,动手搞一下一目了然。
文章评论