V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
star7th
V2EX  ›  程序员

如何利用 showdoc 自动生成数据字典

  •  
  •   star7th · 2018-04-23 11:27:25 +08:00 · 2595 次点击
    这是一个创建于 2166 天前的主题,其中的信息可能已经有所发展或是发生改变。

    介绍

    showdoc 是一个非常适合 IT 团队的在线 API 文档、技术文档工具。你可以使用 Showdoc 来编写在线 API 文档、技术文档、数据字典、在线手册。关于 showdoc 的详细介绍,可看:https://www.showdoc.cc/help

    好的数据字典文档能够清晰地反映出数据库的结构以及相关释义,方便技术人员查阅。我们很容易使用 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   : 认证凭证。登录 showdoc,创建一个项目后,点击右上角的”项目设置”-“开放 API ”便可看到 
     api_token : 同上  
     cat_name: 可选。如果想把生成的文档都放在项目的子目录下,则这里填写子目录名。  
     url:可选。 同步到的 url。如果是使用 www.showdoc.cc ,则不需要再改此项。如果是部署开源版 showdoc,请改此项为 http://xx.com/server/index.php?s=/api/open/updateDbItem。其中 xx.com 为你的部署域名|
    
    
    • 执行
    sh showdoc_db.sh 
    
    

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

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

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

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

    注意事项

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

    2 条回复    2018-04-23 19:04:05 +08:00
    liwl
        1
    liwl  
       2018-04-23 16:09:13 +08:00
    广告?之前有注意这个
    star7th
        2
    star7th  
    OP
       2018-04-23 19:04:05 +08:00
    @liwl 去年发过一篇关于 showdoc 的文章。现在更新了也顺便发一下,顺便提升点知名度。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   3263 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 27ms · UTC 14:02 · PVG 22:02 · LAX 07:02 · JFK 10:02
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.