干掉 Postman？测试接口直接生成API文档，这个工具贼好用

前几天粉丝群有小伙伴问有啥好用的API文档工具推荐无意间发现了一款工具这里马不停蹄的来给大家分享一下。ShowDoc一个非常适合团队的在线API文档工具也支持用docker自建文档服务不过为了方便演示我直接用了平台在线服务。官网地址https://www.showdoc.com.cn/item/index可以使用markdown语法来写API文档、数据字典文档、技术文档、在线excel文档。但像我这种资深的懒人程序员其实更看重的是showdoc的自动化 生成文档的特性它可以从代码注释中自动生成API文档或者搭配RunApi客户端类似postman的api调试工具一边调试接口、一边自动生成文档。下边从头演示下来瞅瞅这玩意好用在哪初识 ShowDocShowDoc新建项目可选常规的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。如下配置的变量名和解释效果就是如下图这样生成了数据表字典文档在一些特定场景下还是很方便的。开放APIshowdoc开放了文档编辑的API我们可以在代码中调用API创建、编辑文档。这样使用的场景就比较灵活了。https://www.showdoc.cc/server/api/item/updateByApiAPI参数如下文档内容可传递markdown格式的文本或者html源码都可以。测试一下接口组装必要的参数用简易在线API调试工具发送{api_key: 8e52cbad736aa9832b92acc4b34a830e961861279,api_token: 9dcd8333afa7cde63bf84f8f0db5d2b2116079256,page_title: xiaofu,page_content: nihao}看到在showdoc对应的项目里已经创建了名字为xiaofu的文档。说两句前边说过showdoc现有的功能postman基本都支持但postman功能过于繁杂不够简洁加上网络条件等诸多限制协同办公的效率并不高而Runapi配合showdoc在某些场景下能够很大程度上提升我们开发交付的效率所以能自动生成的绝对不手写再怎么BB吹嘘都是苍白的好不好用适不适合自己动手搞一下一目了然最后下方这份完整的软件测试 视频教程已经整理上传完成需要的朋友们可以自行领取【保证100%免费】​​​软件测试面试文档我们学习必然是为了找到高薪的工作下面这些面试题是来自阿里、腾讯、字节等一线互联网大厂最新的面试资料并且有字节大佬给出了权威的解答刷完这一套面试资料相信大家都能找到满意的工作。