在团队协作中除了代码的版本管理之外，还有文档管理也是比较重要的，比如数据字典、接口文档之类的，试想如果后台修改了接口导致页面数据显示不正常，责任在谁呢？如果通过一个文档来写明接口的详细信息，该传什么参数该返回什么数据都是清清楚楚，如果修改了接口，只需要通知前端按照文档修改即可，且文档便于维护。

1. 文档分类

• 协同工具：WPS云，石墨，有道云，一起写

• 接口文档：showdoc,eoLinker,MinDoc,apizza

• 其他：gitbook / blog / mock

2. ShowDoc 简介

官网：https://www.showdoc.com.cn/

showdoc主要特性：

• 数据字典、接口模板
• 团队协作
• 免费开源
• 支持本地化部署

3. ShowDoc 本地安装及设置

这次演示是基于docker容器技术，Docker 方式安装官方文档：
https://www.showdoc.com.cn/help?page_id=65610

步骤如下：

# 拉取镜像
docker pull star7th/showdoc 
# 新建存放showdoc数据的目录
mkdir -p /showdoc_data/html
# 设置文件夹权限
chmod  -R 777 /showdoc_data
# 运行docker、映射端口并挂载
docker run -d --name showdoc -p 13500:80 -v /showdoc_data/html/:/var/www/html/ star7th/showdoc

记得将13500端口添加防火墙放行规则（如果开启了防火墙），云服务商的安全组也需要放行这个端口。

然后访问13500端口开始安装:

选择中文，点击【OK】:

点击【进入网站首页】，然后去设置一下密码：

点击登录：

会显示我的项目，刚开始会有几个示例项目，点击【管理后台】图标可以进去做一些设置：

先来设置下管理员密码：

一般不直接使用管理员账号，可以自己注册一个普通账号，后直接在后他管理添加一个普通账号来管理项目。

4. ShowDoc 使用

1. 创建项目
   
   这里选择常规项目，单页项目是没有目录的，一般我们内部使用的属于私密项目，可以设置一个密码才能访问。

2. 团队管理
   
   创建号项目后我们可设置下团队，点击右上角【团队管理】,添加一个团队：

然后给团队分配人员和项目：


还可以设置【成员权限】：

3. 编写文档

打开项目，看到的是空白页面，右边有一些功能按钮，有返回、分享、新建页面、新建/管理目录、编辑页面、复制、历史版本、导出、删除、项目管理等功能：

新建一个试试，选择【API接口模板】就会自动生成一个示例模板，直接在这基础上修改即可：

4. 常见功能

• 分类：新建多个文件夹来对文档按业务功能分类

• 移动目录：在编辑页面最上面可以选择目录

• 排序：在编辑页面最上面点击页面排序可以通过拖拽对文档进行排序

• 导出：在主界面右边的有个下载图标，点击可以导出为word格式或markdown格式

5. 总结

showdoc免费开源，支持本地化部署，简洁实用，适用于小团队或个人项目使用。

什么工具是最好的？---- 适合的才是最好的。