Wizard 是一款開源文檔管理系統，項目地址為 github.com/mylxsw/wizar。這個項目是 我 在2017年就開始開發的，起初只是想做一款能夠在公司內部把Swagger文檔管理起來的工具，但在這近兩年的時間裡，一直斷斷續續的為其添加各種功能，現在終於下決心發布1.0版本了，目前支持三種類型的文檔管理

  • Markdown：也是Wizard最主要的文檔類型，研發團隊日常工作中交流所採用的最常用文檔類型，在 Wizard 中，對 Editor.md 項目進行了功能擴展，增加了文檔模板，Json 轉表格，圖片粘貼上傳等功能

  • Swagger：支持 OpenAPI 3.0 規範，嵌入了 Swagger 官方的編輯器，通過定製開發，使其融入到 Wizard 項目當中，支持文檔模板，全屏編輯，文檔自動同步功能

  • Table：這種文檔類型是類似於 Excel 電子表格，採用了 x-spreadsheet 項目，將該項目嵌入到了 Wizard 中，目前還不是很完善

目前主要包含以下功能

  • Swagger，Markdown，Table 類型的文檔管理
  • 文檔修改歷史管理
  • 文檔修改差異對比
  • 用戶許可權管理
  • 項目分組管理
  • LDAP 統一身份認證
  • 文檔搜索，標籤搜索
  • 閱讀模式
  • 文檔評論
  • 消息通知
  • 文檔分享
  • 統計功能

如果想快速體驗一下Wizard的功能，有兩種方式

  • 在線體驗請訪問 wizard.aicode.cc/ ，目前只提供部分功能的體驗，功能預覽和使用說明請參考 Wiki。
  • 使用Docker來創建一個完整的Wizard服務 進入項目的根目錄，執行 docker-compose up，就可以快速創建一個Wizard服務了，訪問地址 http://localhost:8080 。

起源

為了鼓勵大家寫開發文檔，最開始我們選擇了 ShowDoc 項目來作為文檔管理工具，當時團隊規模也非常的小，大家都是直接用 Markdown 寫一些簡單的開發文檔。後來隨著團隊的壯大，前後端分離，團隊分工的細化，僅僅採用 Markdown 開始變得捉襟見肘，這時候，我們首先想到了使用開源界比較流行的 Swagger 來創建開發文檔。但是 Swagger 文檔多了，總得有個地方維護起來吧？

項目中的文檔僅僅用Swagger也是不夠的，它只適應於API文檔的管理，還有很多其它文檔，比如設計文檔，流程圖，架構文檔，技術方案，資料庫變更等各種文檔需要一起維護起來。因此，我決定利用業餘時間開發一款 支持 Markdown 和 Swagger 的文檔管理工具，也就是 Wizard 項目了。

起初打算用 Go 語言來開發，但是沒過幾天發現使用 Golang 來做 Web 項目開發效率太低（快速開發效率，並非指性能，Golang做API介面開發還是很不錯的），很多常用的功能都需要自己去實現，遂放棄使用 Golang，轉而使用 PHP 的 Laravel 框架來開發。所以雖然項目創建的時間為 2017年7月27日，但是實際上真正開始的時間應該算是 2017年7月31日。

起初Wizard項目的想法比較簡單，只是用來將 Markdown 文檔和 Swagger 文檔放在一起，提供一個簡單的管理界面就足夠了，但是隨著在團隊中展開使用後，發現在企業中作為一款文檔管理工具來說，只提供簡單的文檔管理功能是不夠的，比如說許可權控制，文檔修改歷史，文檔搜索，文檔分類等功能需求不斷的被提出來，因此也促成了 Wizard 項目的功能越來越完善。

  • 用戶許可權管理 參考了 Gitlab 的許可權管理方式，在用戶的身份上只區分了 管理員 和 普通用戶，通過創建用戶組來對用戶的許可權進行細緻的管理，同時每個項目都支持單獨的為用戶賦予讀寫許可權。
  • 項目分組 在 Wizard 中，文檔是以項目為單位進行組織的，剛開始的時候發現這樣是OK的，後來項目越來越多，項目分組功能應運而生，以目錄的形式來組織項目結構。
  • 文檔修改歷史 每次對文檔的修改，Wizard 都會記錄一個快照，避免錯誤的修改了文檔而造成損失，可以通過文檔歷史快速的恢復文檔，對文檔的修改，新增，刪除等關鍵操作都會記錄審計日誌，以最近活動的形式展示出來。
  • 文檔差異對比 在團隊協助中，經常會出現很多人修改同一份文檔，為了避免衝突，文檔修改後，其它人在提交舊的歷史版本時，系統會提示用戶文檔內容發生了變更，用戶可以通過文檔比對功能找出文檔中有哪些內容發生了修改。
  • 閱讀模式 當使用投影儀展示文檔來過技術方案的時候，為了減少不必要的幹擾，使用閱讀模式，只展示文檔內容部分，提供更好的展示體驗。
  • 文檔搜索 通過搜索功能快速查找需要的文檔，目前支持通過文檔標題來搜素文檔，後續會增加全文檢索功能。
  • LDAP支持 很多公司都會使用 LDAP 來統一的管理公司員工的賬號，員工的在公司內部的所有系統中都是用同一套帳號來登錄各種系統比如 Jira，Wiki，Gitlab 等，Wizard 也提供了對 LDAP 的支持，只需要簡單的幾個配置，就可以快速的接入公司的統一帳號體系。
  • 文檔附件，文檔分享，統計，文檔排序，模板管理，文檔評論 ...

關於代碼

項目採用了 Laravel 框架開發，目前版本已經升級到最新的 5.8（最開始為5.4，一路升級過來）。為了提高開發效率，保持架構的簡潔，在開發過程中，一直避免引入過多的外部組件，儘可能的利用 Laravel 提供的各種組件，比如 Authentication，Authorization，Events，Mail，Notifications 等，非常適合用來學習 Laravel 框架。

總結

如果你在為公司尋找一款開源免費的 開發文檔/API文檔管理 工具，不妨考慮一下 Wizard 項目，一定不會讓你失望的。如果你是一名 PHP 或者 Laravel 新手，想找個項目學習一下如何用 Laravel 做 Web 開發，這個項目更加不能錯過！

最後，也是本文最核心的部分，趕緊去 Star 一下，順便給我個 Star 啊 ！如果再能貢獻點 Issues 或者P R，那就更好啦 ??！


推薦閱讀：
相關文章