引领API文档生成新时代：如何利用ShowDoc实现接口测试与文档生成的完美结合，提升团队协作效率

ShowDoc是一个非常适合团队协作的在线API文档工具，支持使用docker自建文档服务。为了便于展示，我选择直接使用其在线服务。官网地址如下：

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

ShowDoc支持使用markdown语法创建API文档、数据字典、技术文档以及在线excel文档。作为一名资深的程序员，我最看重的是ShowDoc的自动文档生成功能，它可以从代码注释中自动生成API文档。配合RunApi客户端（类似于Postman的API调试工具），可以在调试接口的同时自动生成相关文档。

著名科技爱好者阮一峰老师在其最新的周刊中也推荐了这一文档工具。

接下来，我将详细演示一下这个工具的实际应用。

了解ShowDoc的基本功能

在ShowDoc中，新建项目时可以选择常规的API文档、在线表格或单页文档（不支持目录分层），同时允许为项目设置访问密码和自定义域名。需要注意的是，这里的“域名”并不是传统意义上的域名，而是在文档服务域名后加了一级目录，例如：

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

用户可以复制现有项目，或直接导入Postman和swagger的API接口配置JSON文件。ShowDoc的开放API是实现自动化生成文档的关键，建议记住api_key和api_token这两个属性，后续会详细介绍。

在进入项目后，点击右上角的 + 编辑文档，ShowDoc提供了几种预置的文档模板，用户也可以将自定义的文档保存为模板。该工具支持在线Mock服务，允许提前定义好接口的数据格式，以便于前端开发与后端无缝对接。此外，它还提供了简单的API在线测试功能。

在线表格样式简洁清晰。

文档导出支持Word和Markdown两种格式。

此外，ShowDoc还支持版本控制，用户可以查看每次修改的记录，并随时回滚到任意版本。

在分享文档时，如果不希望暴露整个API目录，用户可以选择进行单页面分享。

初看ShowDoc似乎功能一般，但接下来我们将探索如何实现自动化生成文档。

自动生成API文档的多种方式

ShowDoc提供了三种自动生成API文档的方法：

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

使用Runapi工具生成文档

Runapi是一个以接口为核心的开发测试工具，可以看作是Postman的精简版。它支持Windows、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文档。

生成的文档将保存在你填写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"  
}