简介

特点：

• ShowDoc是一个开源、免费的工具
• ShowDoc是一个非常适合IT团队的在线或本地部署的API文档、技术文档实现，它可以实现同步
• 借助ShowDoc可以方便快速地编写出美观的API文档
• ShowDoc提供免费在线文档托管服务，用户可以通过ShowDoc官网创建自己的项目，并将其保存在云端，也可以选择将它部署在本地服务器

本地部署

由于公司项目的特殊性，需要在本地服务器部署一个ShowDoc，这里以CentOS7.0为例。

第一步：安装docker

yum install docker

第二步：启动docker

service docker start

第三步：设置docker开机自启动

chkconfig docker on

第四步：安装git

yum install git

第五步：安装ShowDoc

首先自己建一个文件夹
cd /test
git clone -o gitbug https://github.com/star7th/showdoc
注意：如果报错了Peer reports incompatible or unsupported protocol version，请先更新yum update nss curl再克隆发现就可以了。

第六步：进入目录开始安装

cd shodoc/
docker build -t showdoc ./
docker run -d --name showdoc -p 4999:80 showdoc

安装.png

注意：端口号4999支持自定义

第七步：访问ShowDoc

在浏览器中输入http://IP:4999/install/即可访问（记得把防火墙关了或者防火墙添加策略允许4999端口）。页面如下：

ShowDoc install页面.png
选择语言（默认中文），点击“OK”按钮，弹出安装成功提示框。如下图：
安装成功.png

第八步：备份

API文档是非常重要的文件，需定期备份。/test/showdoc/Sqlite/showdoc.db.php就是这个文件。
可以手动备份，也可以用脚本自动定时备份。此处就不做多介绍了。

大致的界面就是这样子的

界面.png

从图中可以看出，一个完整的API文档应该包含以下几部分：

• 接口名称；
• 简要描述；
• 请求的URL；
• 请求方式
• 请求参数（参数名、是否必选、参数类型、说明）；
• 返回实例；
• 返回参数说明；
• 备注和责任人。