当前位置:首页 > 公众号精选 > 架构师社区
[导读]前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下。ShowDoc一个非常适合团队的在线API文档工具,也支持用docker自建文档服务,不过为了方便演示,我直接用了平台在线服务。官网地址:https://www.showd...


干掉 Postman?测试接口直接生成API文档,这工具真香!

前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下。

ShowDoc一个非常适合团队的在线API文档工具,也支持用docker自建文档服务,不过为了方便演示,我直接用了平台在线服务。官网地址:

ospace;font-size: 12px;-webkit-overflow-scrolling: touch;padding-top: 15px;background: #282c34;border-radius: 5px;">https://www.showdoc.com.cn/item/index
可以使用markdown语法来写API文档、数据字典文档、技术文档、在线excel文档。但像我这种资深的懒人程序员,其实更看重的是showdoc的自动化生成文档的特性,它可以从代码注释中自动生成API文档,或者搭配RunApi客户端(类似postman的api调试工具)一边调试接口、一边自动生成文档。

下边从头演示下,来瞅瞅这玩意好用在哪?

干掉 Postman?测试接口直接生成API文档,这工具真香!
主页

初识 ShowDoc

ShowDoc新建项目可选常规的API文档、在线表格、或者单页文档(不支持目录分层),允许对项目文档设置访问密码,自定义域名,这里并不是真正意义上的“域名”,只是在文档服务域名后加了一级目录,例如:

www.showdoc.com.cn/程序员内点事
干掉 Postman?测试接口直接生成API文档,这工具真香!
可以复制现有的项目,或直接导入Postmanswagger的API接口配置Json文件。提供的开放API是自动化生成文档的关键,先记住有api_keyapi_token这两个属性,后边详细讲。

干掉 Postman?测试接口直接生成API文档,这工具真香!
进入项目后点击右上角 编辑文档,ShowDoc预置了几种文档模板,也可以把自定义的文档存为模板;支持在线Mock服务,提前定义好接口的数据格式,先提供在线临时接口,这样就可以和前端同步开发,后边无缝切换;还有个简单的API在线测试功能。

干掉 Postman?测试接口直接生成API文档,这工具真香!
在线表格样式很简洁

干掉 Postman?测试接口直接生成API文档,这工具真香!
导出文档有wordMarkdown两种格式。

干掉 Postman?测试接口直接生成API文档,这工具真香!
支持版本控制,能看到每次修改的记录,回滚任意一个版本的修改。

干掉 Postman?测试接口直接生成API文档,这工具真香!
在向别人分享在线文档时,如果不想将整个API目录都暴漏,可以选择进行单页面分享。干掉 Postman?测试接口直接生成API文档,这工具真香!

看到这感觉showdoc很普通啊,好像没什么特别的地方,上边的这些文档都是需要我们手动书写的,比较繁琐不推荐这么搞,接下来咱们看看如何自动化生成文档。

自动生成文档

showdoc有三种自动生成API文档的方式:

  • 使用Runapi工具自动生成(推荐
  • 使用程序代码注释自动生成
  • 自动生成数据字典
  • 自己写程序调用接口来生成
Runapi工具

Runapi是一个以接口为核心的开发测试工具(可以看做是Postman的精简版)。目前客户端支持winmaclinux平台和在线版 ,包含接口测试、自动流程测试、Mock数据、项目协作等功能。

单纯的RunapiPostman相比优势并不大,而与showdoc配合使用效率比较显著,用runapi测试接口的同时它将自动生成API文档到showdoc,也可共用showdoc的团队管理机制实现多人协作。

Runapi客户端可以创建带调试的API接口文档、或者Markdown格式的文档。

干掉 Postman?测试接口直接生成API文档,这工具真香!
比如我们新建个项目“程序员内点事”,分别建三个接口“点在”、“在看”、“关注”,紧接着快速生成参数和响应结果数据并保存。

干掉 Postman?测试接口直接生成API文档,这工具真香!
点击右上角的文档链接设置访问密码,不填默认是公开的,复制文档链接在浏览器中打开,看到API接口文档已经生成。runapi还有全局参数、环境隔离。其实Postman也支持这样的功能,不过毕竟不是国内产品,网络访问等方面很受限制。

干掉 Postman?测试接口直接生成API文档,这工具真香!
还有一个比较好的地方,Runapi支持接口执行前后的脚本,比如响应数据的断言测试,弹框显示都挺好用的。

干掉 Postman?测试接口直接生成API文档,这工具真香!

代码注释

把接口的信息写在注释里也可以自动生成文档到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_keyapi_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_keyapi_token变量值,URL如果没搭建自己的文档服务不用改。

干掉 Postman?测试接口直接生成API文档,这工具真香!
showdoc_api.sh放在你的项目目录下,直接双击运行,脚本会自动递归扫描本目录和子目录的所有文本代码文件,并生成API文档。

干掉 Postman?测试接口直接生成API文档,这工具真香!
showdoc_api.sh生成的文档会放进你填写api_token的这个项目里。

干掉 Postman?测试接口直接生成API文档,这工具真香!

生成数据字典

如果我们想直接从数据库字典表生成数据字典文档,showdoc也是支持的,先下载官方提供的脚本

wget https://www.showdoc.cc/script/showdoc_db.sh
修改脚本里的配置,数据库、api_keyapi_token等信息,直接执行后数据库表结构信息同步到showdoc

干掉 Postman?测试接口直接生成API文档,这工具真香!如下配置的变量名和解释干掉 Postman?测试接口直接生成API文档,这工具真香!

效果就是如下图这样,生成了数据表字典文档,在一些特定场景下还是很方便的。

干掉 Postman?测试接口直接生成API文档,这工具真香!

开放API

showdoc开放了文档编辑的API,我们可以在代码中调用API创建、编辑文档。这样使用的场景就比较灵活了。

https://www.showdoc.cc/server/api/item/updateByApi
API参数如下,文档内容,可传递markdown格式的文本或者html源码都可以。

干掉 Postman?测试接口直接生成API文档,这工具真香!
测试一下接口组装必要的参数,用简易在线API调试工具发送

{
  "api_key""8e52cbad736aa9832b92acc4b34a830e961861279",
  "api_token""9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
  "page_title""xiaofu",
  "page_content""nihao"
}
干掉 Postman?测试接口直接生成API文档,这工具真香!看到在showdoc对应的项目里已经创建了名字为xiaofu的文档。干掉 Postman?测试接口直接生成API文档,这工具真香!

说两句

前边说过showdoc现有的功能postman基本都支持,但postman功能过于繁杂不够简洁,加上网络条件等诸多限制,协同办公的效率并不高,而Runapi配合showdoc在某些场景下能够很大程度上提升我们开发交付的效率,所以能自动生成的绝对不手写!

再怎么BB吹嘘都是苍白的,好不好用,适不适合自己,动手搞一下一目了然。

本站声明: 本文章由作者或相关机构授权发布,目的在于传递更多信息,并不代表本站赞同其观点,本站亦不保证或承诺内容真实性等。需要转载请联系该专栏作者,如若文章内容侵犯您的权益,请及时联系本站删除。
换一批
延伸阅读

9月2日消息,不造车的华为或将催生出更大的独角兽公司,随着阿维塔和赛力斯的入局,华为引望愈发显得引人瞩目。

关键字: 阿维塔 塞力斯 华为

加利福尼亚州圣克拉拉县2024年8月30日 /美通社/ -- 数字化转型技术解决方案公司Trianz今天宣布,该公司与Amazon Web Services (AWS)签订了...

关键字: AWS AN BSP 数字化

伦敦2024年8月29日 /美通社/ -- 英国汽车技术公司SODA.Auto推出其旗舰产品SODA V,这是全球首款涵盖汽车工程师从创意到认证的所有需求的工具,可用于创建软件定义汽车。 SODA V工具的开发耗时1.5...

关键字: 汽车 人工智能 智能驱动 BSP

北京2024年8月28日 /美通社/ -- 越来越多用户希望企业业务能7×24不间断运行,同时企业却面临越来越多业务中断的风险,如企业系统复杂性的增加,频繁的功能更新和发布等。如何确保业务连续性,提升韧性,成...

关键字: 亚马逊 解密 控制平面 BSP

8月30日消息,据媒体报道,腾讯和网易近期正在缩减他们对日本游戏市场的投资。

关键字: 腾讯 编码器 CPU

8月28日消息,今天上午,2024中国国际大数据产业博览会开幕式在贵阳举行,华为董事、质量流程IT总裁陶景文发表了演讲。

关键字: 华为 12nm EDA 半导体

8月28日消息,在2024中国国际大数据产业博览会上,华为常务董事、华为云CEO张平安发表演讲称,数字世界的话语权最终是由生态的繁荣决定的。

关键字: 华为 12nm 手机 卫星通信

要点: 有效应对环境变化,经营业绩稳中有升 落实提质增效举措,毛利润率延续升势 战略布局成效显著,战新业务引领增长 以科技创新为引领,提升企业核心竞争力 坚持高质量发展策略,塑强核心竞争优势...

关键字: 通信 BSP 电信运营商 数字经济

北京2024年8月27日 /美通社/ -- 8月21日,由中央广播电视总台与中国电影电视技术学会联合牵头组建的NVI技术创新联盟在BIRTV2024超高清全产业链发展研讨会上宣布正式成立。 活动现场 NVI技术创新联...

关键字: VI 传输协议 音频 BSP

北京2024年8月27日 /美通社/ -- 在8月23日举办的2024年长三角生态绿色一体化发展示范区联合招商会上,软通动力信息技术(集团)股份有限公司(以下简称"软通动力")与长三角投资(上海)有限...

关键字: BSP 信息技术
关闭
关闭