一文教會你如何在內(nèi)網(wǎng)搭建一套屬于自己小組的在線 API 文檔？

時間：2023-07-21 02:36:01 | 來源：網(wǎng)站運營

時間：2023-07-21 02:36:01 來源：網(wǎng)站運營

一文教會你如何在內(nèi)網(wǎng)搭建一套屬于自己小組的在線 API 文檔？：Hello，大家好，我是阿粉，對接文檔是每個開發(fā)人員不可避免都要寫的，友好的文檔可以大大的提升工作效率。

阿粉最近將項目的文檔基于 Gitbook 和 Gitlab 的 Webhook 功能的在內(nèi)網(wǎng)部署了一套實時的，使用起來特方便了。跟著阿粉的步驟，教你部署自己的文檔服務。

步驟

1. 安裝 Node 和 NPM；
2. 安裝 git， gitbook，gitbook-cli；
3. 配置 Gitlab Webhook；
4. 創(chuàng)建 Webhook 監(jiān)聽服務；
5. 編輯文檔檢查實時更新；

安裝 Node，NPM

第一步我們先安裝 Node 和 NPM，

# 下載壓縮包wget https://nodejs.org/dist/v9.10.1/node-v9.10.1-linux-x64.tar.gz# 解壓tar xzvf node-v9.10.1-linux-x64.tar.gz# 重命名mv node-v9.10.1-linux-x64 node# 移動到/usr/local/ 目錄下mv node* /usr/local/# 創(chuàng)建軟連接ln -s /usr/local/node/bin/* /usr/sbin/# 檢查版本node -v# 正常輸出，下面內(nèi)容說明安裝成功> v9.10.1正常安裝完 Node 過后 NPM 會自動安裝，通過npm -v 可以看到 NPM 的版本號。

Gitbook

Git 的安裝阿粉就不演示了，給大家演示安裝 Gitbook，依次執(zhí)行下面的命令。

# 安裝 Gitbooknpm install -g gitbook# 安裝 Gitbook 命令行工具npm install -g gitbook-cli# 創(chuàng)建軟連接ln -s /usr/local/node/bin/gitbook /usr/sbin/gitbook# 查看 Gitbook 版本 注意大寫的 V gitbook -V安裝完 Gitbook 過后，我們這個時候就可以部署服務了，我們先創(chuàng)建一個空文件夾 test-doc，然后進入文件夾執(zhí)行gitbook init 命令，執(zhí)行成功過后，我們可以看到生成了兩個文件，分別是 README.md 以及 SUMMARY.md 文件。

[root@~]# mkdir test-doc[root@~]# cd test-doc/[root@test-doc]# gitbook initwarn: no summary file in this bookinfo: create README.mdinfo: create SUMMARY.mdinfo: initialization is finished[root@test-doc]# ll總用量 8-rw-r--r--. 1 root root 16 12月 6 19:15 README.md-rw-r--r--. 1 root root 40 12月 6 19:15 SUMMARY.md創(chuàng)建完成過后，我們在 test-doc 目錄下執(zhí)行命令 gitbook serve 可以看到如下日志內(nèi)容

我們訪問服務器的 4000 端口，正?？梢钥吹饺缦马撁?。

如果沒有看到上面的內(nèi)容或者訪問不了 4000 端口，我們需要檢查一下服務器的防火墻，先看下防火墻開放的端口，執(zhí)行命令 firewall-cmd --list-ports 看看是否開放了 4000 端口，如果沒有執(zhí)行下面命令 firewall-cmd --zone=public --add-port=4000/tcp --permanent 將 4000 端口進行開放，然后重新 reload，firewall-cmd --reload ，再次刷新瀏覽器即可。

后面的操作就是在文檔中增加相應的內(nèi)容即可，當然這里模擬的是本地創(chuàng)建文件夾，如果我們的文檔已經(jīng)存在倉庫中，我們可以通過 git 將倉庫拉下來，增加 README.md 和 SUMMARY.md 文件，然后編寫相應內(nèi)容即可，只需要在 SUMMARY.md 中增加相應的目錄，同樣啟動就能訪問。

Gitlab Webhook

截止到上面的內(nèi)容我們已經(jīng)部署了一套在線的文檔服務，但是有個比較麻煩的事情，就是每次文檔有所更新的時候，我們在修改完文檔，推送到 Gitlab 倉庫后，都需要手動登錄服務器，然后重新 git pull 拉取最新的文檔，接著重啟 gitbook serve 服務，難免會覺得比較麻煩。

好在 Gitlab 提供 Webhook 功能（GitHub 也一樣提供），我們可以在 Gitlab 對應的倉庫中配置 Webhook功能。Webhook 我們可以理解為鉤子功能，允許我們在對倉庫進行改動過后可以觸發(fā)一個我們指定的服務，然后執(zhí)行相應的動作。

比如我們這里想要的效果就是，在每次更新文檔 push 的倉庫過后，希望部署的在線文檔服務能自動拉取最新的文檔信息，然后自動重啟 gitbook 服務，實現(xiàn)文檔的及時更新。

實現(xiàn)上面的需求，我們需要兩步，第一步在 Gitlab 對應的倉庫里面設置 Webhook ，也就是每次執(zhí)行 push 動作后需要調(diào)用的服務地址；第二步我們需要一個服務，這個服務需要提供一個接口，當被調(diào)用的時候執(zhí)行拉取最新文檔和重啟 gitbook 服務的功能。

為了方便我們可以把拉取最新文檔和重啟 gitbook 服務的功能寫成一個 shell 腳本，當接口被調(diào)用的時候，我們只需要執(zhí)行 shell 腳本即可。

配置 Webhook

找到倉庫的設置，不同版本的 Gitlab 可以頁面顯示不一樣，大家自行找一找就好，

點進去過后我們看到如下頁面，需要填寫服務的地址，這里我們服務還沒有創(chuàng)建，不過我們可以先進行定義，比如阿粉這里就填了 http://xxxx:6666/autobuild，服務器的地址就填寫安裝了 Gitbook 的服務器；在 Secret Token 一欄我們設置一個秘鑰，接口到時候也需要填寫，只要對應上就行，比如 autobuild。

第三個是下面的 Trigger，這里默認選擇的是 Push events，我們不用改，如果需要其他的也可以設置。

再點擊下面的Add webhook 按鈕保存即可。

部署接口服務

我們在剛剛部署了 gitbook 的服務器上面創(chuàng)建一個名為 webhook 的文件夾，在文件夾里面我們創(chuàng)建三個文件，分別是 index.js，package.json，auto_build.sh

index.js 內(nèi)容如下：這里我們的接口名字和 secret需要跟在 Gitlab 上面配置的一樣

var http = require('http');var spawn = require('child_process').spawn;# 導入 Gitlab 的 webhookvar createHandler = require('gitlab-webhook-handler');var handler = createHandler({ path: '/autobuild', secret: 'autobuild' });http.createServer(function (req, res) { handler(req, res, function (err) { res.statusCode = 404; res.end('no such locationsssssssss'); });}).listen(6666);handler.on('error', function (err) { console.error('Error:', err.message)});handler.on('push', function (event) { console.log('Received a push event for %s to %s', event.payload.repository.name, event.payload.ref); runCommand('sh', ['/root/webhook/auto_build.sh'], function( txt ){ console.log(txt); });});function runCommand( cmd, args, callback ){ var child = spawn( cmd, args ); var response = ''; child.stdout.on('data', function( buffer ){ response += buffer.toString(); }); child.stdout.on('end', function(){ callback( response ) }); child.stderr.on('data', (data) => { console.log(`stderr: ${data}`); });}簡單介紹一下上面的 JS 代碼，創(chuàng)建一個服務監(jiān)聽 6666 端口，提供一個名叫 autobuild 的接口，在收到 push 操作的時候就執(zhí)行/root/webhook/auto_build.sh 路徑下的腳本。

auto_build.sh 腳本的內(nèi)容如下：

#! /bin/bashSITE_PATH='/root/test-doc'#USER='admin'#USERGROUP='admin'cd $SITE_PATH#git reset --hard origin/master#git clean -fgit pull# 切換到 dev 分支，可以自己設定git checkout dev# 啟動 gitbooknohup gitbook serve > /dev/null 2>&1 &#chown -R $USER:$USERGROUP $SITE_PATH腳本里面主要就是拉取這新的內(nèi)容，然后切換到 dev 分支，再執(zhí)行gitbook serve 命令，采用的是nohup gitbook serve > /dev/null 2>&1 &

package.json的內(nèi)容如下：

{ "name": "autobuild", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo /"Error: no test specified/" && exit 1" }, "keywords": [], "author": "", "license": "ISC", "dependencies": { "gitlab-webhook-handler": "1.0.1" }}啟動服務器之前，先執(zhí)行npm install 安裝依賴，然后執(zhí)行nohup node index.js &，啟動成功過后我們就可以進行文檔修改然后 push 到Gitlab 上面，觀察是否及時更新。這里注意一個點，我們的腳本里面使用的是 dev 分支，所以要 push 到 dev 分支。

我們可以在 Gitlab 的 Webhook 下面看到我們 push 過后觸發(fā)的詳情，可以看到是否成功。這里如果不成功，我們再檢查下防火墻是否開啟了 6666 端口，沒有的話，按照上面的操作開啟即可。

到這里我們整個基于 Gitbook 和 Gitlab Webhook 實現(xiàn)文檔實時更新的效果就達成了，后續(xù)在使用的時候，我們只需要修改內(nèi)容，然后 push 到對應的倉庫，然后在網(wǎng)站上就能看到最新的修改，大家感興趣可以自己試試哦。

Tips

Gitbook 可以支持插件以及自定義樣式，我們只需要在 test-doc 目錄下面，創(chuàng)建一個名叫 book.json 的文件，可以在這個文件中自定義一些特定的內(nèi)容，增加了插件，在啟動的時候需要使用gitbook install 安裝一下即可。

{ "title": "XXXX對接API", "description": "這是 Gitbook 與 Gitlab Webhook 集成的項目", "author": "Java 極客技術", "plugins": ["splitter","tbfed-pagefooter","expandable-chapters-small"], "pluginsConfig": { "tbfed-pagefooter": { "copyright":"Copyright &copy COOCAA", "modify_label": "該文件修訂時間：", "modify_format": "YYYY-MM-DD HH:mm:ss" } }, "styles": { "website": "./customStyle.css" }styles 下面可以增加我們自己寫的樣式，如果需要的話可以加入。

總結

今天阿粉給大家分享了一個使用的技能，在工作中搭建起來，相信會很有幫助的。有任何問題歡迎在評論區(qū)留言我們一起討論~，原創(chuàng)不宜，如有幫助歡迎點贊分享，一鍵三連。

本文由 mdnice 多平臺發(fā)布