干掉 Postman?测试接口直接生成API文档,这个工具我爱了
前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下。
ShowDoc
一个非常适合团队的在线API文档工具,也支持用docker
自建文档服务,不过为了方便演示,我直接用了平台在线服务。官网地址:
https://www.showdoc.com.cn/item/index
可以使用markdown
语法来写API文档、数据字典文档、技术文档、在线excel
文档。但像我这种资深的懒人程序员,其实更看重的是showdoc
的自动化生成文档的特性,它可以从代码注释中自动生成API文档,或者搭配RunApi
客户端(类似postman的api调试工具)一边调试接口、一边自动生成文档。
下边从头演示下,来瞅瞅这玩意好用在哪?
初识 ShowDoc
ShowDoc
新建项目可选常规的API文档、在线表格、或者单页文档(不支持目录分层),允许对项目文档设置访问密码,自定义域名,这里并不是真正意义上的“域名”,只是在文档服务域名后加了一级目录,例如:
www.showdoc.com.cn/程序员内点事
可以复制现有的项目,或直接导入Postman
、swagger
的API接口配置Json文件。提供的开放API是自动化生成文档的关键,先记住有api_key
、api_token
这两个属性,后边详细讲。
进入项目后点击右上角 + 编辑文档,ShowDoc
预置了几种文档模板,也可以把自定义的文档存为模板;支持在线Mock
服务,提前定义好接口的数据格式,先提供在线临时接口,这样就可以和前端同步开发,后边无缝切换;还有个简单的API在线测试功能。
在线表格样式很简洁
导出文档有word
、Markdown
两种格式。
支持版本控制,能看到每次修改的记录,回滚任意一个版本的修改。
在向别人分享在线文档时,如果不想将整个API目录都暴漏,可以选择进行单页面分享。
看到这感觉showdoc
很普通啊,好像没什么特别的地方,上边的这些文档都是需要我们手动书写的,比较繁琐不推荐这么搞,接下来咱们看看如何自动化生成文档。
自动生成文档
showdoc
有三种自动生成API文档的方式:
使用Runapi工具自动生成(推荐)
使用程序代码注释自动生成
自动生成数据字典
自己写程序调用接口来生成
Runapi工具
Runapi
是一个以接口为核心的开发测试工具(可以看做是Postman
的精简版)。目前客户端支持win
、mac
、linux
平台和在线版 ,包含接口测试、自动流程测试、Mock数据、项目协作等功能。
单纯的Runapi
和Postman
相比优势并不大,而与showdoc
配合使用效率比较显著,用runapi
测试接口的同时它将自动生成API文档到showdoc
,也可共用showdoc
的团队管理机制实现多人协作。
Runapi
客户端可以创建带调试的API接口文档、或者Markdown格式的文档。
比如我们新建个项目“程序员内点事
”,分别建三个接口“点在
”、“在看
”、“关注
”,紧接着快速生成参数和响应结果数据并保存。
点击右上角的文档链接
设置访问密码,不填默认是公开的,复制文档链接在浏览器中打开,看到API接口文档已经生成。runapi还有全局参数、环境隔离。其实Postman
也支持这样的功能,不过毕竟不是国内产品,网络访问等方面很受限制。
还有一个比较好的地方,Runapi
支持接口执行前后的脚本,比如响应数据的断言测试,弹框显示都挺好用的。
代码注释
把接口的信息写在注释里也可以自动生成文档到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如果没搭建自己的文档服务不用改。
将showdoc_api.sh
放在你的项目目录下,直接双击运行,脚本会自动递归扫描本目录和子目录的所有文本代码文件,并生成API文档。
showdoc_api.sh
生成的文档会放进你填写api_token
的这个项目里。
生成数据字典
如果我们想直接从数据库字典表生成数据字典文档,showdoc
也是支持的,先下载官方提供的脚本
wget https://www.showdoc.cc/script/showdoc_db.sh
修改脚本里的配置,数据库、api_key
、api_token
等信息,直接执行后数据库表结构信息同步到showdoc
。
如下配置的变量名和解释
效果就是如下图这样,生成了数据表字典文档,在一些特定场景下还是很方便的。
开放API
showdoc
开放了文档编辑的API,我们可以在代码中调用API创建、编辑文档。这样使用的场景就比较灵活了。
https://www.showdoc.cc/server/api/item/updateByApi
API参数如下,文档内容,可传递markdown格式的文本或者html源码都可以。
测试一下接口组装必要的参数,用简易在线API调试工具发送
{"api_key": "8e52cbad736aa9832b92acc4b34a830e961861279","api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256","page_title": "xiaofu","page_content": "nihao"
}
看到在showdoc
对应的项目里已经创建了名字为xiaofu
的文档。
说两句
前边说过showdoc
现有的功能postman
基本都支持,但postman
功能过于繁杂不够简洁,加上网络条件等诸多限制,协同办公的效率并不高,而Runapi
配合showdoc
在某些场景下能够很大程度上提升我们开发交付的效率,所以能自动生成的绝对不手写!
再怎么BB吹嘘都是苍白的,好不好用,适不适合自己,动手搞一下一目了然
干掉 Postman?测试接口直接生成API文档,这个工具我爱了相关推荐
- 干掉 Postman?测试接口直接生成API文档,这个文档工具真香!
欢迎关注方志朋的博客,回复"666"获面试宝典 实不相瞒我的收藏夹里躺着很多优质的开源项目,我有个爱好平时遇到感兴趣的开源项目都会记录下来,然后有时间在慢慢研究.前几天刚给同事分享 ...
- 干掉 Swagger + Postman?测试接口直接生成API文档,这个国产文档工具真香!
点击上方"芋道源码",选择"设为星标" 管她前浪,还是后浪? 能浪的浪,才是好浪! 每天 10:33 更新文章,每天掉亿点点头发... 源码精品专栏 原创 | ...
- 干掉 Postman?测试接口直接生成API文档,这工具真香!
前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下. ShowDoc一个非常适合团队的在线API文档工具,也支持用docker自建文档服务,不过 ...
- 干掉Postman?测试接口直接生成API文档,这工具强烈推荐!
最近被身边几个做开发的朋友安利了一款国产的 API 开发调试神器,真的有被惊艳到!!!简直不要太好用! 没想到,中国也有了比 Postman 还好用的软件! 这个 API 开发调试神器就是 ApiPo ...
- 干掉 Postman?测试接口直接生成 API 文档,这工具真香!
作者:小 G 来源:GitHubDaily " 阅读本文大概需要 5 分钟. " 前阵子,偶然发现一款国产 API 接口开发调试神器,上手尝鲜之后,真的有被惊艳到,功能齐全,对中文 ...
- 干掉 Postman?测试接口直接生成API文档,这个工具贼好用
大家好,我是小码哥~ 前几天粉丝群有小伙伴问,有啥好用的API文档工具推荐,无意间发现了一款工具,这里马不停蹄的来给大家分享一下. ShowDoc一个非常适合团队的在线API文档工具,也支持用dock ...
- springfox源码_【开源项目】springfox-bridge:随心所欲地为非restful接口生成API文档...
一.引言 目前,利用swagger框架为restful接口编写API文档非常流行,在spring web项目中,利用springfox+swagger更是可以通过注解的方式直接进行API文档的生成,这 ...
- 【接口文档】Django restful framework中自动生成API文档
Django restful framework中自动生成API文档 一.Swagger概述 1.引言 当接口开发完成,紧接着需要编写接口文档.传统的接口文档使用Word编写,or一些接口文档管理平台 ...
- .NET Core 3.0 使用Nswag生成Api文档和客户端代码
摘要 在前后端分离.Restful API盛行的年代,完美的接口文档,成了交流的纽带.在项目中引入Swagger (也称为OpenAPI),是种不错的选择,它可以让接口数据可视化.下文将会演示 利用N ...
最新文章
- 基因组重复序列检测:RepeatMasker
- Gabor滤波小结整理
- 网站渗透测试,看这篇就够了
- 5g理论速度_5G网络相当于500M宽带是真的吗?
- 模板:二维线段树(线段树套线段树)
- mysql c#开发库_c# 开发+MySql数据库
- Yii 多表关联relations
- 对象的持久化和序列化
- 模仿 alexa 工具条
- (转)关于第一行代码中NotificationCompat失效的解决方法
- 华为手机桌面计算机消失怎么办,华为手机桌面所以图标不见了怎么办
- 思科交换机配置远程登录命令
- 超级实习生计划项目练习——JavaScript 利用Ajax制作一个汇率转换器
- 信必优成功案例 – 中国网络电视台(CNTV)
- 傻瓜数码相机拍摄技巧
- 如何使用C#把数据写到EXCEL文档中
- Citrix PVS无盘系统最小环境搭建
- Jetson 系列——Jetson Nano使用sudo命令免输入密码方法
- 电机matlab程序计算公式,MATLAB用于电机电磁计算的计算机编程
- Python与ADB的基情四射(一)——简单命令
热门文章
- 2021汤家凤1800题数学一PDF_【重要更新】朱伟9720年英语一二真题解析视频 唐迟罗汉班 谭剑波作文 新东方英语 文都数学汤家凤...
- 教你如何防范远程桌面协议(RDP)的安全威胁
- 云原生安全的挑战与实践
- 【Java】反射( reflection)机制 详解
- 关于学习Python的一点学习总结(30->递归实例)
- codeforces数学1700[CodeForces 1336B[分类讨论+二分]CodeForces - 1301C[组合计数的减法原理]]
- 7怎么导入中文文献_如何下载并引用参考文献?
- Codeforces 1499D - The Number of Pairs(数论 + 组合计数)
- 51nod 1038 X^A Mod P( N 次剩余)
- 刷题 - 基础数学/数论问题