摘要：總結(jié)如果你在為公司尋找一款開源免費(fèi)的開發(fā)文檔文檔管理工具，不妨考慮一下項(xiàng)目，一定不會(huì)讓你失望的。

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

Markdown：也是Wizard最主要的文檔類型，研發(fā)團(tuán)隊(duì)日常工作中交流所采用的最常用文檔類型，在 Wizard 中，對(duì) Editor.md 項(xiàng)目進(jìn)行了功能擴(kuò)展，增加了文檔模板，Json 轉(zhuǎn)表格，圖片粘貼上傳等功能

Swagger：支持 OpenAPI 3.0 規(guī)范，嵌入了 Swagger 官方的編輯器，通過(guò)定制開發(fā)，使其融入到 Wizard 項(xiàng)目當(dāng)中，支持文檔模板，全屏編輯，文檔自動(dòng)同步功能

Table：這種文檔類型是類似于 Excel 電子表格，采用了 x-spreadsheet 項(xiàng)目，將該項(xiàng)目嵌入到了 Wizard 中，目前還不是很完善

目前主要包含以下功能

Swagger，Markdown，Table 類型的文檔管理

文檔修改歷史管理

文檔修改差異對(duì)比

用戶權(quán)限管理

項(xiàng)目分組管理

LDAP 統(tǒng)一身份認(rèn)證

文檔搜索，標(biāo)簽搜索

閱讀模式

文檔評(píng)論

消息通知

文檔分享

統(tǒng)計(jì)功能

如果想快速體驗(yàn)一下Wizard的功能，有兩種方式

在線體驗(yàn)請(qǐng)?jiān)L問(wèn) http://wizard.aicode.cc/ ，目前只提供部分功能的體驗(yàn)，功能預(yù)覽和使用說(shuō)明請(qǐng)參考 Wiki。

使用Docker來(lái)創(chuàng)建一個(gè)完整的Wizard服務(wù)

進(jìn)入項(xiàng)目的根目錄，執(zhí)行 docker-compose up，就可以快速創(chuàng)建一個(gè)Wizard服務(wù)了，訪問(wèn)地址 http://localhost:8080 。

為了鼓勵(lì)大家寫開發(fā)文檔，最開始我們選擇了 ShowDoc 項(xiàng)目來(lái)作為文檔管理工具，當(dāng)時(shí)團(tuán)隊(duì)規(guī)模也非常的小，大家都是直接用 Markdown 寫一些簡(jiǎn)單的開發(fā)文檔。后來(lái)隨著團(tuán)隊(duì)的壯大，前后端分離，團(tuán)隊(duì)分工的細(xì)化，僅僅采用 Markdown 開始變得捉襟見(jiàn)肘，這時(shí)候，我們首先想到了使用開源界比較流行的 Swagger 來(lái)創(chuàng)建開發(fā)文檔。但是 Swagger 文檔多了，總得有個(gè)地方維護(hù)起來(lái)吧？

項(xiàng)目中的文檔僅僅用Swagger也是不夠的，它只適應(yīng)于API文檔的管理，還有很多其它文檔，比如設(shè)計(jì)文檔，流程圖，架構(gòu)文檔，技術(shù)方案，數(shù)據(jù)庫(kù)變更等各種文檔需要一起維護(hù)起來(lái)。因此，我決定利用業(yè)余時(shí)間開發(fā)一款 支持 Markdown 和 Swagger 的文檔管理工具，也就是 Wizard 項(xiàng)目了。

起初打算用 Go 語(yǔ)言來(lái)開發(fā)，但是沒(méi)過(guò)幾天發(fā)現(xiàn)使用 Golang 來(lái)做 Web 項(xiàng)目開發(fā)效率太低（快速開發(fā)效率，并非指性能，Golang做API接口開發(fā)還是很不錯(cuò)的），很多常用的功能都需要自己去實(shí)現(xiàn)，遂放棄使用 Golang，轉(zhuǎn)而使用 PHP 的 Laravel 框架來(lái)開發(fā)。所以雖然項(xiàng)目創(chuàng)建的時(shí)間為 2017年7月27日，但是實(shí)際上真正開始的時(shí)間應(yīng)該算是 2017年7月31日。

起初Wizard項(xiàng)目的想法比較簡(jiǎn)單，只是用來(lái)將 Markdown 文檔和 Swagger 文檔放在一起，提供一個(gè)簡(jiǎn)單的管理界面就足夠了，但是隨著在團(tuán)隊(duì)中展開使用后，發(fā)現(xiàn)在企業(yè)中作為一款文檔管理工具來(lái)說(shuō)，只提供簡(jiǎn)單的文檔管理功能是不夠的，比如說(shuō)權(quán)限控制，文檔修改歷史，文檔搜索，文檔分類等功能需求不斷的被提出來(lái)，因此也促成了 Wizard 項(xiàng)目的功能越來(lái)越完善。

用戶權(quán)限管理 參考了 Gitlab 的權(quán)限管理方式，在用戶的身份上只區(qū)分了 管理員 和 普通用戶，通過(guò)創(chuàng)建用戶組來(lái)對(duì)用戶的權(quán)限進(jìn)行細(xì)致的管理，同時(shí)每個(gè)項(xiàng)目都支持多帶帶的為用戶賦予讀寫權(quán)限。

項(xiàng)目分組 在 Wizard 中，文檔是以項(xiàng)目為單位進(jìn)行組織的，剛開始的時(shí)候發(fā)現(xiàn)這樣是OK的，后來(lái)項(xiàng)目越來(lái)越多，項(xiàng)目分組功能應(yīng)運(yùn)而生，以目錄的形式來(lái)組織項(xiàng)目結(jié)構(gòu)。

文檔修改歷史 每次對(duì)文檔的修改，Wizard 都會(huì)記錄一個(gè)快照，避免錯(cuò)誤的修改了文檔而造成損失，可以通過(guò)文檔歷史快速的恢復(fù)文檔，對(duì)文檔的修改，新增，刪除等關(guān)鍵操作都會(huì)記錄審計(jì)日志，以最近活動(dòng)的形式展示出來(lái)。

文檔差異對(duì)比 在團(tuán)隊(duì)協(xié)助中，經(jīng)常會(huì)出現(xiàn)很多人修改同一份文檔，為了避免沖突，文檔修改后，其它人在提交舊的歷史版本時(shí)，系統(tǒng)會(huì)提示用戶文檔內(nèi)容發(fā)生了變更，用戶可以通過(guò)文檔比對(duì)功能找出文檔中有哪些內(nèi)容發(fā)生了修改。

閱讀模式 當(dāng)使用投影儀展示文檔來(lái)過(guò)技術(shù)方案的時(shí)候，為了減少不必要的干擾，使用閱讀模式，只展示文檔內(nèi)容部分，提供更好的展示體驗(yàn)。

文檔搜索 通過(guò)搜索功能快速查找需要的文檔，目前支持通過(guò)文檔標(biāo)題來(lái)搜素文檔，后續(xù)會(huì)增加全文檢索功能。

LDAP支持 很多公司都會(huì)使用 LDAP 來(lái)統(tǒng)一的管理公司員工的賬號(hào)，員工的在公司內(nèi)部的所有系統(tǒng)中都是用同一套帳號(hào)來(lái)登錄各種系統(tǒng)比如 Jira，Wiki，Gitlab 等，Wizard 也提供了對(duì) LDAP 的支持，只需要簡(jiǎn)單的幾個(gè)配置，就可以快速的接入公司的統(tǒng)一帳號(hào)體系。

文檔附件，文檔分享，統(tǒng)計(jì)，文檔排序，模板管理，文檔評(píng)論 ...

項(xiàng)目采用了 Laravel 框架開發(fā)，目前版本已經(jīng)升級(jí)到最新的 5.8（最開始為5.4，一路升級(jí)過(guò)來(lái)）。為了提高開發(fā)效率，保持架構(gòu)的簡(jiǎn)潔，在開發(fā)過(guò)程中，一直避免引入過(guò)多的外部組件，盡可能的利用 Laravel 提供的各種組件，比如 Authentication，Authorization，Events，Mail，Notifications 等，非常適合用來(lái)學(xué)習(xí) Laravel 框架。

如果你在為公司尋找一款開源免費(fèi)的 開發(fā)文檔/API文檔管理 工具，不妨考慮一下 Wizard 項(xiàng)目，一定不會(huì)讓你失望的。如果你是一名 PHP 或者 Laravel 新手，想找個(gè)項(xiàng)目學(xué)習(xí)一下如何用 Laravel 做 Web 開發(fā)，這個(gè)項(xiàng)目更加不能錯(cuò)過(guò)！

最后，也是本文最核心的部分，趕緊去 Star 一下，順便給我個(gè) Star 啊 ！如果再能貢獻(xiàn)點(diǎn) Issues 或者P R，那就更好啦