Wizard 是一款開源文檔管理系統(tǒng)俯在，項目地址為 https://github.com/mylxsw/wizard。這個項目是 我 在2017年就開始開發(fā)的娃惯，起初只是想做一款能夠在公司內(nèi)部把Swagger文檔管理起來的工具跷乐，但在這近兩年的時間里，一直斷斷續(xù)續(xù)的為其添加各種功能石景，現(xiàn)在終于下決心發(fā)布1.0版本了劈猿，目前支持三種類型的文檔管理

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

  -w590

• Swagger：支持 OpenAPI 3.0 規(guī)范佛舱，嵌入了 Swagger 官方的編輯器椎例，通過定制開發(fā)，使其融入到 Wizard 項目當中请祖，支持文檔模板订歪，全屏編輯，文檔自動同步功能

  -w594

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

  -w592

目前主要包含以下功能

• Swagger慎陵，Markdown眼虱，Table 類型的文檔管理
• 文檔修改歷史管理
• 文檔修改差異對比
• 用戶權限管理
• 項目分組管理
• LDAP 統(tǒng)一身份認證
• 文檔搜索，標簽搜索
• 閱讀模式
• 文檔評論
• 消息通知
• 文檔分享
• 統(tǒng)計功能

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

• 在線體驗請訪問 http://wizard.aicode.cc/ 捏悬，目前只提供部分功能的體驗，功能預覽和使用說明請參考 Wiki润梯。

• 使用Docker來創(chuàng)建一個完整的Wizard服務

  進入項目的根目錄过牙，執(zhí)行 docker-compose up，就可以快速創(chuàng)建一個Wizard服務了纺铭，訪問地址 http://localhost:8080 抒和。

起源

為了鼓勵大家寫開發(fā)文檔，最開始我們選擇了 ShowDoc 項目來作為文檔管理工具彤蔽，當時團隊規(guī)模也非常的小摧莽，大家都是直接用 Markdown 寫一些簡單的開發(fā)文檔。后來隨著團隊的壯大顿痪，前后端分離镊辕，團隊分工的細化油够，僅僅采用 Markdown 開始變得捉襟見肘，這時候征懈，我們首先想到了使用開源界比較流行的 Swagger 來創(chuàng)建開發(fā)文檔石咬。但是 Swagger 文檔多了，總得有個地方維護起來吧卖哎？

項目中的文檔僅僅用Swagger也是不夠的鬼悠，它只適應于API文檔的管理，還有很多其它文檔亏娜，比如設計文檔焕窝，流程圖，架構文檔维贺，技術方案它掂，數(shù)據(jù)庫變更等各種文檔需要一起維護起來。因此溯泣，我決定利用業(yè)余時間開發(fā)一款 支持 Markdown 和 Swagger 的文檔管理工具虐秋，也就是 Wizard 項目了。

起初打算用 Go 語言來開發(fā)垃沦，但是沒過幾天發(fā)現(xiàn)使用 Golang 來做 Web 項目開發(fā)效率太低（快速開發(fā)效率客给，并非指性能，Golang做API接口開發(fā)還是很不錯的）肢簿，很多常用的功能都需要自己去實現(xiàn)靶剑，遂放棄使用 Golang，轉而使用 PHP 的 Laravel 框架來開發(fā)译仗。所以雖然項目創(chuàng)建的時間為 2017年7月27日抬虽，但是實際上真正開始的時間應該算是 2017年7月31日。

-w986

起初Wizard項目的想法比較簡單纵菌，只是用來將 Markdown 文檔和 Swagger 文檔放在一起阐污，提供一個簡單的管理界面就足夠了，但是隨著在團隊中展開使用后咱圆，發(fā)現(xiàn)在企業(yè)中作為一款文檔管理工具來說笛辟，只提供簡單的文檔管理功能是不夠的，比如說權限控制序苏，文檔修改歷史手幢，文檔搜索，文檔分類等功能需求不斷的被提出來忱详，因此也促成了 Wizard 項目的功能越來越完善围来。

• 用戶權限管理 參考了 Gitlab 的權限管理方式，在用戶的身份上只區(qū)分了 管理員 和 普通用戶，通過創(chuàng)建用戶組來對用戶的權限進行細致的管理监透，同時每個項目都支持單獨的為用戶賦予讀寫權限桶错。
• 項目分組 在 Wizard 中，文檔是以項目為單位進行組織的胀蛮，剛開始的時候發(fā)現(xiàn)這樣是OK的院刁，后來項目越來越多，項目分組功能應運而生粪狼，以目錄的形式來組織項目結構退腥。
• 文檔修改歷史 每次對文檔的修改，Wizard 都會記錄一個快照再榄，避免錯誤的修改了文檔而造成損失狡刘，可以通過文檔歷史快速的恢復文檔，對文檔的修改不跟，新增颓帝，刪除等關鍵操作都會記錄審計日志米碰，以最近活動的形式展示出來窝革。
• 文檔差異對比 在團隊協(xié)助中，經(jīng)常會出現(xiàn)很多人修改同一份文檔吕座，為了避免沖突虐译，文檔修改后，其它人在提交舊的歷史版本時吴趴，系統(tǒng)會提示用戶文檔內(nèi)容發(fā)生了變更漆诽，用戶可以通過文檔比對功能找出文檔中有哪些內(nèi)容發(fā)生了修改。
• 閱讀模式 當使用投影儀展示文檔來過技術方案的時候锣枝，為了減少不必要的干擾厢拭，使用閱讀模式，只展示文檔內(nèi)容部分撇叁，提供更好的展示體驗供鸠。
• 文檔搜索 通過搜索功能快速查找需要的文檔，目前支持通過文檔標題來搜素文檔陨闹，后續(xù)會增加全文檢索功能楞捂。
• LDAP支持 很多公司都會使用 LDAP 來統(tǒng)一的管理公司員工的賬號，員工的在公司內(nèi)部的所有系統(tǒng)中都是用同一套帳號來登錄各種系統(tǒng)比如 Jira趋厉，Wiki寨闹，Gitlab 等，Wizard 也提供了對 LDAP 的支持君账，只需要簡單的幾個配置繁堡，就可以快速的接入公司的統(tǒng)一帳號體系。
• 文檔附件，文檔分享椭蹄，統(tǒng)計矮瘟，文檔排序，模板管理塑娇，文檔評論 ...

關于代碼

項目采用了 Laravel 框架開發(fā)澈侠，目前版本已經(jīng)升級到最新的 5.8（最開始為5.4，一路升級過來）埋酬。為了提高開發(fā)效率哨啃，保持架構的簡潔，在開發(fā)過程中写妥，一直避免引入過多的外部組件拳球，盡可能的利用 Laravel 提供的各種組件，比如 Authentication珍特，Authorization祝峻，Events，Mail扎筒，Notifications 等莱找，非常適合用來學習 Laravel 框架。

總結

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

最后层亿，也是本文最核心的部分吮螺，趕緊去 Star 一下绊谭，順便給我個 Star 啊 脖苏！如果再能貢獻點 Issues 或者P R塘秦，那就更好啦 ??！