如何利用showdoc自動生成資料字典

star7th發表於2019-02-16

介紹

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來刪除。一般來講，這種情況不會很多。

相關文章