大家好，我是小富~

前几天粉丝群有小伙伴问，有啥好用的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吹牛都是红润的，好不好用，适不适宜本人，入手搞一下高深莫测

我是小富，下期见~

整顿了几百本各类技术电子书，有须要的同学自取。技术群快满了，想进的同学能够加我好友，和大佬们一起吹吹技术。

电子书地址