自动生成数据字典

介绍

好的数据字典文档能够清晰地反映出数据库的结构以及相关释义,方便技术人员查阅。我们很容易使用showdoc来生成展示数据库结构的字典文档,并且能根据数据库结构的变动来自动修改文档,省去人工编辑的麻烦。
这一切的自动化依赖于我们的上报脚本。你需要下载我们的脚本到你的服务器上执行,上传数据库结构信息到showdoc。上报脚本的源码完全公开,你可以阅读之以确认安全。我们确保它只会上传基本数据库结构信息,不会上传数据库密码配置、业务数据等敏感信息。
目前只支持linux下的mysql数据库,更多类型未来再考虑。

操作步骤

  • 执行下载脚本的命令

    wget https://www.showdoc.cc/script/showdoc_db.sh
    
  • 打开此文件

    vi showdoc_db.sh
    
  • 修改配置信息
    打开文件后,在文件的前面能看到几项配置。其中,像数据库配置、api_key等信息是需要你填写的,填写完毕后保存即可。下面用表格的形式列举出各个配置项代表的意思。

项目 解释
host 数据库所在地址。默认是localhost
port 数据库访问端口,默认是3306
user 数据库用户名
password 密码
db 要同步的数据库名。要同步多个db可以将本脚本复制多份
api_key api_key,认证凭证。登录showdoc,创建一个项目后,点击右上角的”项目设置”-“开放API”便可看到
api_token 同上
cat_name 可选。如果想把生成的文档都放在项目的子目录下,则这里填写子目录名。需要创建多层目录的时候请用斜杆隔开,例如 “一层/二层/三层”
url 可选。同步到的url。如果是使用www.showdoc.com.cn ,则不需要再改此项。如果是部署私有版showdoc,请改此项为http://xx.com/server/index.php?s=/api/open/updateDbItem 。其中xx.com为你的部署域名
  • 执行

    chmod +x showdoc_db.sh
    ./showdoc_db.sh
    

    看到成功字样便ok。你可以打开showdoc项目看看是否真的生成了。

  • 定时自动更新

    如果想定时自动更新,则需要为系统增加一个定时任务。下面给一个例子,表示每10分钟同步一次

    /10 * * * *  /root/showdoc_db.sh
    

    其中,showdoc_db.sh脚本在定时任务里需要写绝对路径。

注意事项

如果你设置了脚本的自动执行,那么请不要再手动登录showdoc修改文档。因为你的修改都会被自动脚本重新覆盖。
因为会覆盖你的修改,所以如果你想为某个字段设置中文注释,请修改mysql字段注释,而不是在showdoc上手动编辑文档。
自动执行的情况下,只会自动新增和修改文档,不会自动删除文档(主要出于数据安全考虑)。所以,如果你删除了一张表,文档里是不会删除那个页面的。需要手动登录showdoc来删除。一般来讲,这种情况不会很多。