共计 3147 个字符，预计需要花费 8 分钟才能阅读完成。
大家好，我是小富~
前几天粉丝群有小伙伴问，有啥好用的 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/updateByApiAPI 参数如下，文档内容，可传递 markdown 格局的文本或者 html 源码都能够。
测试一下接口组装必要的参数，用繁难在线 API 调试工具发送
{
"api_key": "8e52cbad736aa9832b92acc4b34a830e961861279",
"api_token": "9dcd8333afa7cde63bf84f8f0db5d2b2116079256",
"page_title": "xiaofu",
"page_content": "nihao"
}
看到在 showdoc 对应的我的项目里曾经创立了名字为 xiaofu 的文档。
说两句
前边说过 showdoc 现有的性能 postman 根本都反对，但 postman 性能过于繁冗不够简洁，加上网络条件等诸多限度，协同办公的效率并不高，而 Runapi 配合 showdoc 在某些场景下可能很大水平上晋升咱们开发交付的效率，所以能主动生成的相对不手写！
再怎么 BB 吹牛都是红润的，好不好用，适不适宜本人，入手搞一下高深莫测
我是小富，下期见~
整顿了几百本各类技术电子书，有须要的同学自取。技术群快满了，想进的同学能够加我好友，和大佬们一起吹吹技术。
电子书地址