接口文档系统
- 前言
- 一、ShowDoc简介
- 二、ShowDoc部署
- 三、接口测试文档示例
前言
功能测试的依据有产品需求文档、开发设计文档等，而接口测试的主要依据是接口测试文档。由于前后端分离，用传统的Word文件维护接口文档的方式已经不合时宜，现在，越来越多的团队采用API文档工具来维护接口信息，以下将详细介绍一个维护接口的在线系统。
一、ShowDoc简介
目前，有很多维护API文档工具，本文选择ShowDoc，主要因为ShowDoc有以下特点：
（1）ShowDoc是一个开源、免费的工具。
（2）ShowDoc是一个非常适合IT团队的在线API文档、技术文档工具，它可实现实时同步，用户无须花费过多的精力维护文档。
（3）借助ShowDoc可以方便、快速的编写出美观的API文档，并且还可以用它编辑数据字典、说明书和一些技术规范说明文档供团队查阅。
（4）ShowDoc提供免费在线文档托管服务，用户可以通过ShowDoc官网创建自己的项目，并将其保存在云端，也可以选择将ShowDoc部署到本地服务器。
二、ShowDoc部署
既然ShowDoc已经提供了在线文档托管服务，为什么还要搭建本地服务器呢？这主要是从安全角度进行考虑，毕竟接口文档不适合暴露在“众目睽睽之下”，下面主要讲解如何在本地服务器上部署ShowDoc。
ShowDoc有很多种部署方式，下面以在Docker中部署为例。
这里假设服务器系统为CentOs7
（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，打开如图所示的页面(注意：将IP地址及端口号替换成用户自己服务器的IP地址及（6）中设置的端口号)。
选择语言（默认为中文），单击“OK”按钮，弹出安装成功提示框如图所示，
然后按照提示信息删除/install目录，使用如下命令进行删除（其中的XXX为install路径）
rm -rf XXX/install（8）备份
API文档是非常重要的文档，需要定期备份。/XXX/showdoc/Sqlite下面有个showdoc.db.php文件，定期备份该文件即可。
用户可以采用手动命令备份，使用如下mv命令：
mv /XXX/showdoc/Sqlite/showdoc.db.php /test/showdoc.db.php.dak上面示例将showdoc.db.php文件重命名为show.db.php.dak文件保存在/test目录下，也可以编写自动化备份脚本定期备份，此处不做过多介绍。
注：Docker是一个开源的应用容器引擎，让开发者可以打包他们的应用及依赖包到一个可移植的容器中，然后发布到Linux系统上，也可以实现虚拟化。容器完全使用沙箱机制，互相之间不会有任何接口。
三、接口测试文档示例
目前，有的公司可能没有接口文档，或者测试人员没有查看接口文档的权限，读者可以通过本文的项目接口文档进行了解（如图）
从图看出，一个完整的API文档应该包含一下几部分：
（1）接口名称
（2）简要描述
（3）请求的URL
（4）请求方式（POST/GET）
（5）请求参数（参数名、是否必选、参数类型、说明）
（6）返回示例
（7）返回参数说明
（8）备注及责任人
