如何利用showdoc自動生成數(shù)據(jù)字典

banana_pi 發(fā)布于2019-06-25 18:37 / 3638人閱讀

摘要：關(guān)于的詳細(xì)介紹，可看好的數(shù)據(jù)字典文檔能夠清晰地反映出數(shù)據(jù)庫的結(jié)構(gòu)以及相關(guān)釋義，方便技術(shù)人員查閱。自動執(zhí)行的情況下，只會自動新增和修改文檔，不會自動刪除文檔主要出于數(shù)據(jù)安全考慮。

介紹

showdoc是一個非常適合IT團(tuán)隊的在線API文檔、技術(shù)文檔工具。你可以使用Showdoc來編寫在線API文檔、技術(shù)文檔、數(shù)據(jù)字典、在線手冊。關(guān)于showdoc的詳細(xì)介紹，可看：https://www.showdoc.cc/help

好的數(shù)據(jù)字典文檔能夠清晰地反映出數(shù)據(jù)庫的結(jié)構(gòu)以及相關(guān)釋義，方便技術(shù)人員查閱。我們很容易使用showdoc來生成展示數(shù)據(jù)庫結(jié)構(gòu)的字典文檔，并且能根據(jù)數(shù)據(jù)庫結(jié)構(gòu)的變動來自動修改文檔，省去人工編輯的麻煩。

這一切的自動化依賴于我們的上報腳本。你需要下載我們的腳本到你的服務(wù)器上執(zhí)行，上傳數(shù)據(jù)庫結(jié)構(gòu)信息到showdoc。上報腳本的源碼完全公開，你可以閱讀之以確認(rèn)安全。我們確保它只會上傳基本數(shù)據(jù)庫結(jié)構(gòu)信息，不會上傳數(shù)據(jù)庫密碼配置、業(yè)務(wù)數(shù)據(jù)等敏感信息。

目前只支持linux下的mysql數(shù)據(jù)庫，更多類型未來再考慮。

操作步驟

執(zhí)行下載腳本的命令

wget https://www.showdoc.cc/script/showdoc_db.sh

打開此文件

vi showdoc_db.sh

修改配置信息
打開文件后，在文件的前面能看到幾項配置。其中，像數(shù)據(jù)庫配置、api_key等信息是需要你填寫的，填寫完畢后保存即可。下面列舉出各個配置項代表的意思。

 host ： 數(shù)據(jù)庫所在地址。默認(rèn)是localhost  
 port  :  數(shù)據(jù)庫訪問端口，默認(rèn)是3306 
 user  :  數(shù)據(jù)庫用戶名 
 password   :  密碼 
 db  :  要同步的數(shù)據(jù)庫名。要同步多個db可以將本腳本復(fù)制多份 |
 api_key   ： 認(rèn)證憑證。登錄showdoc，創(chuàng)建一個項目后，點擊右上角的”項目設(shè)置”-“開放API”便可看到 
 api_token : 同上  
 cat_name: 可選。如果想把生成的文檔都放在項目的子目錄下，則這里填寫子目錄名。  
 url ：可選。 同步到的url。如果是使用www.showdoc.cc ，則不需要再改此項。如果是部署開源版showdoc，請改此項為http://xx.com/server/index.php?s=/api/open/updateDbItem 。其中xx.com為你的部署域名|

執(zhí)行

sh showdoc_db.sh

看到成功字樣便ok。你可以打開showdoc項目看看是否真的生成了。

如果想定時自動更新，則需要為系統(tǒng)增加一個定時任務(wù)。下面給一個例子，表示每10分鐘同步一次

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

其中，showdoc_db.sh腳本在定時任務(wù)里需要寫絕對路徑。

注意事項

如果你設(shè)置了腳本的自動執(zhí)行，那么請不要再手動登錄showdoc修改文檔。因為你的修改都會被自動腳本重新覆蓋。
因為會覆蓋你的修改。所以如果你想為某個字段設(shè)置中文注釋，請修改mysql字段注釋，而不是在showdoc上手動編輯文檔。
自動執(zhí)行的情況下，只會自動新增和修改文檔，不會自動刪除文檔（主要出于數(shù)據(jù)安全考慮）。所以，如果你刪除了一張表，文檔里是不會刪除那個頁面的。需要手動登錄showdoc來刪除。一般來講，這種情況不會很多。