Wizard開源項目（API）文檔管理工具

Wizard 是基于Laravel開發(fā)框架開發(fā)的一款開源項目（API）文檔管理工具。 

目前支持三種類型的文檔管理

• Markdown：也是Wizard最主要的文檔類型，研發(fā)團(tuán)隊日常工作中交流所采用的最常用文檔類型，在 Wizard 中，對 Editor.md 項目進(jìn)行了功能擴(kuò)展，增加了文檔模板，Json 轉(zhuǎn)表格，圖片粘貼上傳等功能
• Swagger：支持 OpenAPI 3.0 規(guī)范，嵌入了 Swagger 官方的編輯器，通過定制開發(fā)，使其融入到 Wizard 項目當(dāng)中，支持文檔模板，全屏編輯，文檔自動同步功能
• Table：這種文檔類型是類似于 Excel 電子表格，采用了 x-spreadsheet 項目，將該項目嵌入到了 Wizard 中，目前還不是很完善

在Wizard中，正在編輯的文檔會定時自動保存到本地的 Local Storage 中，避免錯誤關(guān)閉頁面而造成編輯內(nèi)容丟失。

目前主要包含以下功能

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

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

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

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

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

起源

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

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

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

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

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

關(guān)于代碼

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

安裝

目前支持兩種安裝方式，如果你熟悉Docker，可以直接使用Docker容器的方式來運行該項目，這也是最簡單的方式了。如果你沒有使用Docker或者不知道什么是Docker，那么請直接參考手動安裝部分。

通過 Docker 安裝

我們需要創(chuàng)建一個Dockerfile，在Dockerfile中添加環(huán)境配置，比如我采用了宿主機(jī)上安裝的MySQL服務(wù)器，就有了下面的這段Dockerfile配置

FROM mylxsw/wizard:latest

# 數(shù)據(jù)庫連接配置
# 這里可以根據(jù)需要添加其它的Env配置，可用選項參考項目的.env.example文件
ENV DB_CONNECTION=mysql
ENV DB_HOST=host.docker.internal
ENV DB_PORT=3306
ENV DB_DATABASE=wizard_2
ENV DB_USERNAME=wizard
ENV DB_PASSWORD=wizard
ENV WIZARD_NEED_ACTIVATE=false

# 文件上傳存儲目錄
VOLUME /webroot/storage/app/public

RUN php artisan config:cache

執(zhí)行構(gòu)建

docker build -t my-wizard .

數(shù)據(jù)庫初始化

docker run -it --rm --name my-wizard my-wizard php artisan migrate:install
docker run -it --rm --name my-wizard my-wizard php artisan migrate

運行

docker run -d --name my-wizard -p 8080:80  my-wizard

然后就可以通過 http://localhost:8080 訪問 Wizard 了。

手動安裝

手動安裝方式需要先安裝配置好PHP環(huán)境，建議采用 PHP-FPM/Nginx 的方式來運行，具體配置參考 環(huán)境依賴 部分。

環(huán)境依賴

以下組件的安裝配置這里就不做詳細(xì)展開，可以自行 百度/Google 安裝方法。

• PHP 7.2 + (需要啟用 LDAP 擴(kuò)展)
• composer.phar
• MySQL 5.6 +
• Nginx
• Git

下載代碼

推薦使用 git 來下載項目代碼到服務(wù)器，我們假定將該項目放在服務(wù)器的 /data/webroot 目錄

cd /data/webroot
git clone https://github.com/mylxsw/wizard.git
cd wizard

下載代碼之后，使用 composer 安裝項目依賴

composer install --prefer-dist --ignore-platform-reqs

composer 會在在項目目錄中創(chuàng)建 vender 目錄，其中包含了項目所依賴的所有第三方代碼庫。

你也可以直接到項目的 release 頁面直接下載包含依賴的軟件包。

配置

復(fù)制一份配置文件

cp .env.example .env

修改 .env 中的配置信息，比如 MySQL 連接信息，文件存儲目錄，項目網(wǎng)址等。

接下來創(chuàng)建數(shù)據(jù)庫，提前在MySQL中創(chuàng)建好項目的數(shù)據(jù)庫，然后在項目目錄執(zhí)行下面的命令

php artisan migrate:install
php artisan migrate

接下來配置文件上傳目錄

php artisan storage:link

執(zhí)行該命令后會在 public 目錄下創(chuàng)建 storage/app/public 目錄的符號鏈接。

在Nginx中配置項目的訪問地址

server {
    listen       80;
    server_name  wizard.example.com;
    root         /data/webroot/wizard/public;
    index        index.php;

    location / {
        index index.php index.html index.htm;
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ .*\.(gif|jpg|png|bmp|swf|js|css)$ {
        try_files $uri  =302;
    }
    
    location ~ .*\.php$ {
        # php-fpm 監(jiān)聽地址，這里用了socket方式
        fastcgi_pass  unix:/usr/local/php/var/run/php-cgi.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_index index.php;
        include fastcgi_params;
    }
}

升級

項目升級過程非常簡單，只需要使用git拉取最新代碼（git pull），然后執(zhí)行下面的命令完成數(shù)據(jù)庫遷移和依賴更新就OK了。

composer install --prefer-dist --ignore-platform-reqs
php artisan migrate

初始化

安裝完成后，Wizard項目就可以通過瀏覽器訪問了，接下來需要訪問注冊頁面創(chuàng)建初始用戶

http://項目地址/register

在系統(tǒng)中注冊的第一個用戶為默認(rèn)管理員角色。

開發(fā)計劃

•  開發(fā)框架升級Laravel 5.8
•  新版本更新
  •  自動檢測是否有新版本
  •  無損更新版本
•  markdown編輯器增加json轉(zhuǎn)換為markdown表格的功能
•  增加空間管理，類似于命名空間，不同部門在自己的空間中管理項目，文檔等
•  項目功能
  •  項目新增
  •  項目配置
  •  項目權(quán)限分配
  •  項目刪除
  •  支持對項目進(jìn)行分組，首頁分組展示
  •  關(guān)注項目優(yōu)先展示
•  文檔歷史管理，文檔恢復(fù)
•  操作日志記錄
•  國際化支持
•  markdown編輯器增加圖片上傳支持
•  文檔差異比較，文檔歷史版本差異比較
•  基于git的文檔差異分析
•  文檔多人編輯避免內(nèi)容沖突覆蓋
•  個人文檔置頂（個人關(guān)注的文檔，在首頁增加展示區(qū)域，方便快速進(jìn)入）
•  全局文檔置頂（重要的常用文檔，由管理員設(shè)置在首頁特定區(qū)域展示，方便快速進(jìn)入）
•  全文檢索（文檔，項目，評論，標(biāo)簽）
•  搜索功能優(yōu)化，大部分用戶都認(rèn)為首頁項目欄目頂部的搜索是用來搜索文檔的，因此搜索不到
•  圖片拖拽上傳
•  復(fù)制自動上傳
•  文檔管理
  •  文檔編輯
  •  新增文檔
  •  支持Swagger格式文檔
  •  支持markdown文檔
  •  支持表格類型的文檔
  •  文檔刪除
  •  跨項目移動文檔（移動時級聯(lián)選擇項目-目錄）
  •  文檔點贊
•  文檔菜單支持折疊
•  權(quán)限組，分組權(quán)限，管理員權(quán)限
  •  項目按照分組分配讀寫權(quán)限
  •  項目按照用戶分配讀寫權(quán)限
•  文檔模板管理
  •  另存為模板
  •  編輯器選擇模板
  •  模板列表
  •  模板更新
  •  模板刪除
•  文檔排序，支持在文檔配置中國年修改文檔排序
•  文檔排序優(yōu)化：以拖動的方式進(jìn)行排序
•  文檔快速在項目內(nèi)部變更目錄
•  項目排序
•  文檔標(biāo)簽
•  文檔評論
  •  實現(xiàn)最基本的評論功能
  •  實現(xiàn)評論回復(fù)，帶層級的評論
  •  實現(xiàn)評論支持@某人
  •  評論點贊，類似Github issue評論后的emoji
  •  實現(xiàn)評論支持@用戶組下所有用戶
•  消息通知功能
  •  支持@某人后收到消息
  •  支持消息列表
  •  新的消息提示
  •  消息全部已讀，部分已讀
  •  新消息郵件提醒
  •  消息接收配置（站內(nèi)信，郵件，接收類型）
•  關(guān)注項目
  •  關(guān)注項目，取消關(guān)注
  •  已關(guān)注項目列表
  •  關(guān)注項目變更后接收消息通知
•  支持導(dǎo)出文件
  •  導(dǎo)出pdf
  •  導(dǎo)出markdown、swagger
  •  導(dǎo)出word
  •  文檔批量導(dǎo)出
•  實現(xiàn)API接口管理，自動根據(jù)接口數(shù)據(jù)判斷接口是否需要修改，手動觸發(fā)文檔同步
•  對接postman，實現(xiàn)自動生成接口文檔，接口測試
•  實現(xiàn)頁面中之間互相引用
•  項目列表分頁展示，增加按照項目標(biāo)題搜索
•  文檔增加標(biāo)題搜索
•  文檔保存后彈框提示選擇：繼續(xù)編輯還是創(chuàng)建新文檔
•  文檔分享
  •  分享鏈接
  •  分享后的文檔頁面，單頁面模式
  •  分享鏈接管理
  •  分享鏈接有效期設(shè)置
  •  分享鏈接刪除
•  文檔附件
  •  附件上傳
  •  附件展示
  •  附件刪除
  •  附件重傳（歷史附件）
  •  文檔，評論內(nèi)引用附件
•  用戶管理
  •  用戶姓名自動轉(zhuǎn)拼音，用于引用該用戶時快速提示和搜素
  •  用戶部門管理，用于不同部門使用不同空間
  •  用戶登錄，注冊，找回密碼
  •  基本信息修改
  •  修改密碼
  •  管理員分配
  •  用戶分組管理
    •  管理員管理分組
    •  分組基礎(chǔ)數(shù)據(jù)結(jié)構(gòu)支持
  •  用戶管理頁面，增加為用戶分配用戶組的功能，簡化新員工入職時，權(quán)限分配的工作量
  •  LDAP支持
•  統(tǒng)計信息查看
  •  用戶數(shù)量統(tǒng)計
  •  文檔數(shù)量統(tǒng)計
  •  評論數(shù)量統(tǒng)計
  •  用戶活躍度統(tǒng)計
  •  文檔更新統(tǒng)計