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

admin 管理员组

文章数量: 887016

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

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

shell

复制代码

https://www.showdoc/item/index

可以使用markdown语法来写API文档、数据字典文档、技术文档、在线excel文档。但像我这种资深的懒人程序员，其实更看重的是showdoc的自动化生成文档的特性，它可以从代码注释中自动生成API文档，或者搭配RunApi客户端（类似postman的api调试工具）一边调试接口、一边自动生成文档。

下边从头演示下，来瞅瞅这玩意好用在哪？

初识 ShowDoc

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

复制代码

www.showdoc/程序员内点事

可以复制现有的项目，或直接导入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，但这种我并不太喜欢，主要是侵入性比较强，让代码的阅读性变的比较差，一坨坨看着很不爽。

perl

复制代码

/** * showdoc * @catalog 测试文档/用户相关 * @title 用户注册 * @description 用户注册的接口 * @method post * @url https://www.showdoc/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环境：

ruby

复制代码

https://npm.taobao/mirrors/git-for-windows/v2.17.0.windows.1/Git-2.17.0-64-bit.exe

再下载showdoc官方提供的脚本

arduino

复制代码

https://www.showdoc/script/showdoc_api.sh

修改showdoc_api.sh，替换我们api_key和api_token变量值，URL如果没搭建自己的文档服务不用改。

将showdoc_api.sh放在你的项目目录下，直接双击运行，脚本会自动递归扫描本目录和子目录的所有文本代码文件，并生成API文档。

showdoc_api.sh生成的文档会放进你填写api_token的这个项目里。

生成数据字典

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

arduino

复制代码

wget https://www.showdoc/script/showdoc_db.sh

修改脚本里的配置，数据库、api_key、api_token等信息，直接执行后数据库表结构信息同步到showdoc。

如下配置的变量名和解释

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

开放API

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

ruby

复制代码

https://www.showdoc/server/api/item/updateByApi

API参数如下，文档内容，可传递markdown格式的文本或者html源码都可以。

测试一下接口组装必要的参数，用简易在线API调试工具发送

json

复制代码

{ "api_key": "8e52cbad736aa9832b92acc4b34a830e961861279", "api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256", "page_title": "xiaofu", "page_content": "nihao" }

看到在showdoc对应的项目里已经创建了名字为xiaofu的文档。

说两句

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

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

  总结

如果你对此文有任何疑问，如果你也需要接口项目实战，如果你对软件测试、接口测试、自动化测试、面试经验交流感兴趣欢迎加入我们，加入方式在文章的最后面

  自动化测试相关教程推荐：

2023最新自动化测试自学教程新手小白26天入门最详细教程,目前已有300多人通过学习这套教程入职大厂！！_哔哩哔哩_bilibili

2023最新合集Python自动化测试开发框架【全栈/实战/教程】合集精华，学完年薪40W+_哔哩哔哩_bilibili

测试开发相关教程推荐

2023全网最牛，字节测试开发大佬现场教学，从零开始教你成为年薪百万的测试开发工程师_哔哩哔哩_bilibili

postman/jmeter/fiddler测试工具类教程推荐

讲的最详细JMeter接口测试/接口自动化测试项目实战合集教程，学jmeter接口测试一套教程就够了！！_哔哩哔哩_bilibili

2023自学fiddler抓包，请一定要看完【如何1天学会fiddler抓包】的全网最详细视频教程！！_哔哩哔哩_bilibili

2023全网封神，B站讲的最详细的Postman接口测试实战教学，小白都能学会_哔哩哔哩_bilibili

  总结：

 光学理论是没用的，要学会跟着一起敲，要动手实操，才能将自己的所学运用到实际当中去，这时候可以搞点实战案例来学习。

​​​

​​​

如果对你有帮助的话，点个赞收个藏，给作者一个鼓励。也方便你下次能够快速查找。

如有不懂还要咨询下方小卡片，博主也希望和志同道合的测试人员一起学习进步

在适当的年龄，选择适当的岗位，尽量去发挥好自己的优势。

我的自动化测试开发之路，一路走来都离不每个阶段的计划，因为自己喜欢规划和总结，

测试开发视频教程、学习笔记领取传送门！！

​

​

本文标签： 好用 接口 文档 测试 工具