还在为word文档传来传去查阅不方便而烦恼吗，还在为查看数据库字段含义不方便而烦恼吗，还在为编写接口文档而烦恼吗？今天为大家推荐一款适合IT团队的在线API文档、技术文档工具，有免费开源和在线托管的版本。可以直接使用官网搭建好的地址，也可以在自己的服务器上搭建。

官网地址:https://www.showdoc.com.cn/

具备以下特点：

1、可以方便快速编写出美观的API文档

2、用ShowDoc可以编辑出美观的数据字典

3、可以团队协作编写项目文档

4、可从代码注释中自动生成api文档，同时搭配RunApi客户端，可调试接口和自动生成文档

安装方法：服务器上搭建环境，现在我都倾向于用docker的方式，比较方便，不容易出错。

docker pull star7th/showdoc
# 创建一个目录，用来存储数据
mkdir -p /root/docker_volume/showdoc
# 给目录授权
chmod  -R 777 /root/docker_volume/showdoc
# 启动容器
docker run -d --name showdoc --user=root --privileged=true -p 8084:80 -v /root/showdoc:/var/www/html/ star7th/showdoc

启动容器后，输入ip+端口访问，会出现如下页面，让你选择语言，然后就可以开始使用了。

安装好之后，默认的帐号密码是 showdoc/123456

登录之后，会出现几个默认的的示例项目：

点击具体的项目，可以看到相关的文档demo:

整体来说，还是可以满足日常的一些文档的需求的。

在使用过程中或者想了解其他安装方式以及相关问题可以查看官方的帮助文档：

https://www.showdoc.com.cn/help?page_id=1385767280275683

下面介绍一个自动同步数据库表结构到showdoc的方法，以后想看表结构以及字段含义，再也不要登录数据库去执行desc xxxtable的命令了。

目前暂时只支持linux下mysql数据库
# 从官网下载脚本
wget https://www.showdoc.cc/script/showdoc_db.sh
vi showdoc_db.sh
# 然后按照提示修改相关的内容即可
host ：数据库所在地址。默认是localhost
port  :  数据库访问端口，默认是3306
user  :  数据库用户名
password   :  密码
db  :  要同步的数据库名。要同步多个db可以将本脚本复制多份 |
api_key   ： 认证凭证。登录showdoc，创建一个项目后，点击右上角的”项目设置”-“开放API”便可看到
api_token : 同上
cat_name: 可选。如果想把生成的文档都放在项目的子目录下，则这里填写子目录名。
url ：可选。 同步到的url。如果是使用www.showdoc.cc ，则不需要再改此项。如果是部署开源版showdoc，请改此项为http://xx.com/server/index.php?s=/api/open/updateDbItem 。其中xx.com为你的部署域名|

# 修改好脚本后，执行脚本，登录showdoc网站就可看到效果
sh showdoc_db.sh # 可在linux系统上添加定时任务，定时自动的同表结构
vim task.crontab
# 在文件中写下如下内容：
*/10 * * * *  /root/docker_volume/showdoc/showdoc_db.sh
(注意改成自己脚本的路径，执行间隔时间也可以自己调整)然后执行
crontab task.crontab  开启定时任务
定时任务使用上有问题，可以参考菜鸟教程的文章：
https://www.runoob.com/linux/linux-comm-crontab.html

接下来给你们看下我配置的同步之前部署的linjiashop网站的一个数据库的效果：

其实这个数据的同步都是利用showdoc本身的接口进行写入的，采用定时任务之后，要避免在对应的数据字典中去在线修改，可能会被定时同步给覆盖掉。

另外，showdoc官网也提供了swagger接口文档转showdoc的功能，不过是用dotnet语言写的代码，环境搭建起来比较麻烦，用到的有一个框架，微软已经下载不到对应的版本了，所以用不了。在github/gitee上也有不少自己用java代码写的解析swagger的json文件，然后调用api接口同步接口文档到showdoc的，感兴趣的小伙伴可以去试一试喔。如果自己的项目没有接口文档的话，可以让开发在代码中加上showdoc的注解，然后可以自动生成接口文档喔。

END

谢谢您的阅读！