文章目录
- 1. 文档分类
- 2. ShowDoc 简介
- 3. ShowDoc 本地安装及设置
- 4. ShowDoc 使用
- 5. 总结
在团队协作中除了代码的版本管理之外,还有文档管理也是比较重要的,比如数据字典、接口文档之类的,试想如果后台修改了接口导致页面数据显示不正常,责任在谁呢?如果通过一个文档来写明接口的详细信息,该传什么参数该返回什么数据都是清清楚楚,如果修改了接口,只需要通知前端按照文档修改即可,且文档便于维护。
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 使用
- 创建项目 这里选择常规项目,单页项目是没有目录的,一般我们内部使用的属于私密项目,可以设置一个密码才能访问。
- 团队管理 创建号项目后我们可设置下团队,点击右上角【团队管理】,添加一个团队:
然后给团队分配人员和项目:
还可以设置【成员权限】:
- 编写文档
打开项目,看到的是空白页面,右边有一些功能按钮,有返回、分享、新建页面、新建/管理目录、编辑页面、复制、历史版本、导出、删除、项目管理等功能:
新建一个试试,选择【API接口模板】就会自动生成一个示例模板,直接在这基础上修改即可:
- 常见功能
- 分类:新建多个文件夹来对文档按业务功能分类
- 移动目录:在编辑页面最上面可以选择目录
- 排序:在编辑页面最上面点击页面排序可以通过拖拽对文档进行排序
- 导出:在主界面右边的有个下载图标,点击可以导出为word格式或markdown格式
5. 总结
showdoc免费开源,支持本地化部署,简洁实用,适用于小团队或个人项目使用。
什么工具是最好的?---- 适合的才是最好的。