干掉 Postman？测试接口直接生成API文档，这个工具我爱了

左手的ㄟ右手 2022-09-08 15:57 208阅读 0赞

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

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

https://www.showdoc.com.cn/item/index

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

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

![6d4bb7bea6f77e0062cf6faa164cf4b9.png][] 主页

### 初识 ShowDoc ###

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

www.showdoc.com.cn/程序员内点事

![8e97bdf8a17f8cc2ac4db07dddc260d4.png][]

可以复制现有的项目，或直接导入`Postman`、`swagger`的API接口配置Json文件。提供的开放API是自动化生成文档的关键，先记住有`api_key`、`api_token`这两个属性，后边详细讲。

![60824b01fb0fec39ca597b57fd08eb55.png][]

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

![8962cb4994361361544c4ebc4f5f19c5.png][]

在线表格样式很简洁

![7dffd480e79e126fd5b4207f65d93999.png][]

导出文档有`word`、`Markdown`两种格式。

![75f39766c16300a2855695019301c719.png][]

支持版本控制，能看到每次修改的记录，回滚任意一个版本的修改。

![8a10a6359dbd255436ec318cab3477f0.png][]

在向别人分享在线文档时，如果不想将整个API目录都暴漏，可以选择进行单页面分享。![de2f2ec66e051009947d107edc5d7812.png][]

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

### 自动生成文档 ###

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

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

**Runapi工具**

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

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

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

![736354e13578110a8da2f7cc77f2771f.png][]

比如我们新建个项目“`程序员内点事`”，分别建三个接口“`点在`”、“`在看`”、“`关注`”，紧接着快速生成参数和响应结果数据并保存。

![cf26e8195a9445c30b43e968720df631.png][]

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

![0c82d786342e646e01dee10cf4cc21b2.png][]

还有一个比较好的地方，`Runapi`支持接口执行前后的脚本，比如响应数据的断言测试，弹框显示都挺好用的。

![47704fb5b51e2a16fc60281f1514e7ed.png][]

### 代码注释 ###

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

![7caad70019e45a0dd47b33ab768cd3e2.png][]

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

![87b9aca4215fdd217a3a49ef1f26516e.png][]

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

![55f92d92151e65d39e21222a631288d1.png][]

### 生成数据字典 ###

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

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

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

![c972d32a9afa1880312badf292b85d3e.png][]如下配置的变量名和解释![bcb4d14575409647d085a9991a4074ac.png][]

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

![508370b48e4b8078dd8c5e47216dc22f.png][]

### 开放API ###

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

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

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

![1f5376f341174a4c240a0bb805da6693.png][]

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

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

![9eef8ef728406890937eb4699defaf84.png][]看到在`showdoc`对应的项目里已经创建了名字为`xiaofu`的文档。![ac53ae9a832cb077a28bca46977f0ef8.png][]

### 说两句 ###

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

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

推荐阅读：

*  [程序员简历“造假”，被发现后竟然还被高薪录取了………][Link 1]
 *  [世界第三大浏览器正在消亡][Link 2]
 *  [牛逼的Git！！！][Git]
 *  [假如HR面试时都说真话……][HR]

**![a87d3133f32506e8f831e0820576cd57.png][]喜欢我可以给我设为星标哦![e2a630900fcb4f68bf79c80fd2028b3a.png][]**

![0783acb024d926a2003dea862d2853a2.png][]

![0bb9a88157b612a518e22fec306d3303.png][]

**好文章，我****“在看”**

[6d4bb7bea6f77e0062cf6faa164cf4b9.png]: /images/20220829/f5529096d99e41ca8d739787fe635095.png
[8e97bdf8a17f8cc2ac4db07dddc260d4.png]: /images/20220829/e661ee68e80546cc988cdc19716326c3.png
[60824b01fb0fec39ca597b57fd08eb55.png]: /images/20220829/3d1e9fd61677498291005e6683394e14.png
[8962cb4994361361544c4ebc4f5f19c5.png]: /images/20220829/bd84a9b3315840d2b241d161f392636b.png
[7dffd480e79e126fd5b4207f65d93999.png]: /images/20220829/d1ba56c722804941bf9067f9d01f644c.png
[75f39766c16300a2855695019301c719.png]: /images/20220829/4cfeb90f84ae43fd80732af7125e9862.png
[8a10a6359dbd255436ec318cab3477f0.png]: /images/20220829/5c87bd91fda940fbb7f96467f7f43108.png
[de2f2ec66e051009947d107edc5d7812.png]: /images/20220829/e95d60793be644a3b9b09df8716a5747.png
[736354e13578110a8da2f7cc77f2771f.png]: /images/20220829/ccfcffed9b6449759dea224fcb5d3d6b.png
[cf26e8195a9445c30b43e968720df631.png]: /images/20220829/2d000f59f28e4966b0acae3ab3957f6a.png
[0c82d786342e646e01dee10cf4cc21b2.png]: /images/20220829/520739b6fe644a7f9ce97b1308166aaa.png
[47704fb5b51e2a16fc60281f1514e7ed.png]: /images/20220829/91d9df64bae24c4586e2a7df1a3c647c.png
[7caad70019e45a0dd47b33ab768cd3e2.png]: /images/20220829/bb242c7be6864594af679939273653e3.png
[87b9aca4215fdd217a3a49ef1f26516e.png]: /images/20220829/edf1842c33fe47fea340e84bf853bca7.png
[55f92d92151e65d39e21222a631288d1.png]: /images/20220829/67039f5101384ea79ed6d52e4378f71d.png
[c972d32a9afa1880312badf292b85d3e.png]: https://img-blog.csdnimg.cn/img_convert/c972d32a9afa1880312badf292b85d3e.png
[bcb4d14575409647d085a9991a4074ac.png]: /images/20220829/93f376d99d8245c0824d13d5031f7366.png
[508370b48e4b8078dd8c5e47216dc22f.png]: /images/20220829/1a229916b8a04ea6837d46837725303f.png
[1f5376f341174a4c240a0bb805da6693.png]: /images/20220829/b276b1a1c80e4663a98404b4134e19a3.png
[9eef8ef728406890937eb4699defaf84.png]: https://img-blog.csdnimg.cn/img_convert/9eef8ef728406890937eb4699defaf84.png
[ac53ae9a832cb077a28bca46977f0ef8.png]: /images/20220829/0b74af5a3de14dd7bef77b329089ae36.png
[Link 1]: http://mp.weixin.qq.com/s?__biz=Mzg3MjA4MTExMw%3D%3D&chksm=cef63f07f981b61194fc1b457a729f594db470e1fa11fbcca93426efd7dceddac9f762cb4247&idx=1&mid=2247503025&scene=21&sn=12d1fda68db4dd28346779574cb3bb02#wechat_redirect
[Link 2]: http://mp.weixin.qq.com/s?__biz=Mzg3MjA4MTExMw%3D%3D&chksm=cef63f19f981b60fd86c1a8181df1934a265da6678adaf373414fff6394d88bb1992726f11fb&idx=1&mid=2247503023&scene=21&sn=00fd863ad37c8a75f2b4973768b3ec4f#wechat_redirect
[Git]: http://mp.weixin.qq.com/s?__biz=Mzg3MjA4MTExMw%3D%3D&chksm=cef63f1af981b60c69b9c5378a0077bb0bff965bc490210cd0a8e00455992fe8c59212f31f2c&idx=1&mid=2247503020&scene=21&sn=ee91f9b0d341d2a910fcf80171afba1e#wechat_redirect
[HR]: http://mp.weixin.qq.com/s?__biz=Mzg3MjA4MTExMw%3D%3D&chksm=cef63f1ef981b608a368bac949b3afb39ad788c81a3fbbf983cdc6618b34ec3eba67314f82fb&idx=1&mid=2247503016&scene=21&sn=a04b9fbbc519a4b2a1dff4e308a83e1e#wechat_redirect
[a87d3133f32506e8f831e0820576cd57.png]: https://img-blog.csdnimg.cn/img_convert/a87d3133f32506e8f831e0820576cd57.png
[e2a630900fcb4f68bf79c80fd2028b3a.png]: /images/20220829/8d6f12eae907411bb7bc22df84d729b3.png
[0783acb024d926a2003dea862d2853a2.png]: /images/20220829/9b4206757f1a4e8c9cac3930c18faa08.png
[0bb9a88157b612a518e22fec306d3303.png]: /images/20220829/78b13a17934e425496b71754e9ad8a4b.png