1.4 接口文档系统
功能测试的依据有产品需求文档、开发设计文档等，而接口测试的主要依据是接口测试文档。由于前后端分离，用传统的Word文件来维护接口文档的方式已经不合时宜，现在，越来越多的团队采用API文档工具来维护接口信息。本节将详细介绍一个维护接口文档的在线系统。
1.4.1 ShowDoc简介
目前，有很多维护API文档的工具，本书选择ShowDoc，主要因为ShowDoc有以下特点。
① ShowDoc是一个开源、免费的工具。
② ShowDoc是一个非常适合IT团队的在线API文档、技术文档工具，它可实现实时同步，用户无须花费过多的精力维护文档。
③ 借助ShowDoc可以方便、快速地编写出美观的API文档，并且还可以用它编辑数据字典、说明书和一些技术规范说明文档供团队查阅。
④ ShowDoc提供免费在线文档托管服务，用户可以通过ShowDoc官网创建自己的项目，并将其保存在云端，也可以选择将ShowDoc部署到本地服务器。
1.4.2 ShowDoc部署
既然ShowDoc已经提供了在线文档托管服务，为什么还要搭建本地服务呢？这主要是从安全角度进行考虑，毕竟接口文档不适合暴露在“众目睽睽之下”，下面主要讲解如何在本地服务器上部署ShowDoc。
ShowDoc有很多种部署方式，下面以在Docker中部署为例。
这里假设服务器操作系统为CentOS 7。
（1）安装Docker
登录本地服务器，切换到root用户，使用以下命令进行安装。
yum install docker
（2）启动Docker服务
启动命令如下所示。
service docker start
（3）设置Docker服务为开机启动
设置命令如下所示。
chkconfig docker on
（4）借助yum命令，安装git
安装命令如下所示。
yum install git
（5）安装ShowDoc
从GitHub上复制代码到本地某个目录，这里进入根目录下的test文件夹。
cd /test git clone -o gitbug https://github.com/star7th/showdoc
（6）进入ShowDoc目录开始安装
cd showdoc/ docker build -t showdoc ./ docker run -d --name showdoc -p 4999：80 showdoc
注意 ► 如果想在不同端口启动，请修改4999为其他端口。
（7）访问ShowDoc
在浏览器中输入网址http://192.168.132.132:4999/install/，打开如图1-5所示的页面（注意将IP地址及端口号替换成用户自己服务器的IP地址及步骤（6）中设置的端口号）。
图1-5 ShowDoc install页面
选择语言（默认为中文），单击“OK”按钮，弹出安装成功提示框，如图1-6所示。
图1-6 安装成功
然后按照提示信息删除/install目录，使用如下命令进行删除（其中的XXX为install路径）。
rm -rf XXX/install
（8）备份
API文档是非常重要的文档，需定期备份。/XXX/showdoc/Sqlite下面有个showdoc.db.php文件，定期备份该文件即可。
用户可以采用手动命令备份，使用如下mv命令。
e.g. mv /XXX/showdoc/Sqlite/showdoc.db.php /test/showdoc.db.php.bak
上面示例将showdoc.db.php文件重命名为showdoc.db.php.bak文件保存在/test目录下，也可以编写自动化备份脚本定期备份，此处不做过多介绍。
注：Docker是一个开源的应用容器引擎，让开发者可以打包他们的应用及依赖包到一个可移植的容器中，然后发布到Linux系统上，也可以实现虚拟化。容器完全使用沙箱机制，相互之间不会有任何接口。
1.4.3 接口测试文档示例
目前，有的公司可能没有接口文档，或者测试人员没有查看接口文档的权限，读者可以通过本书的项目接口文档进行了解（见图1-7～图1-9）。
图1-7 接口文档示例（一）
图1-8 接口文档示例（二）
图1-9 接口文档示例（三）
从图1-7～图1-9可以看出，一个完整的API文档应该包含以下几部分。
① 接口名称。
② 简要描述。
③ 请求的URL。
④ 请求方式（GET / POST等）。
⑤ 请求参数（参数名、是否必选、参数类型、说明）。
⑥ 返回示例。
⑦ 返回参数说明（参数名、类型、说明）。
⑧ 备注及责任人。