Wizard 開源文檔管理系統1.0發佈啦

Wizard 是一款開源文檔管理系統，項目地址爲 github.com/mylxsw/wiza…。這個項目是 我 在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，那就更好啦 😄！