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

Hello，大家好，我是阿粉，對(duì)接文檔是每個(gè)開發(fā)人員不可避免都要寫的，友好的文檔可以大大的提升工作效率。

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

步驟

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

安裝 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
# 移動(dòng)到/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 會(huì)自動(dòng)安裝，通過npm -v 可以看到 NPM 的版本號(hào)。

Gitbook

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

# 安裝 Gitbook
npm 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 過后，我們這個(gè)時(shí)候就可以部署服務(wù)了，我們先創(chuàng)建一個(gè)空文件夾 test-doc，然后進(jìn)入文件夾執(zhí)行gitbook init 命令，執(zhí)行成功過后，我們可以看到生成了兩個(gè)文件，分別是 README.md 以及 SUMMARY.md 文件。

[root@~]# mkdir test-doc
[root@~]# cd test-doc/
[root@test-doc]# gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: 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)建完成過后，我們?cè)?test-doc 目錄下執(zhí)行命令 gitbook serve 可以看到如下日志內(nèi)容

我們?cè)L問服務(wù)器的 4000 端口，正?？梢钥吹饺缦马撁妗?/p>

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

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

Gitlab Webhook

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

好在 Gitlab 提供 Webhook 功能（GitHub 也一樣提供），我們可以在 Gitlab 對(duì)應(yīng)的倉庫中配置 Webhook功能。Webhook 我們可以理解為鉤子功能，允許我們?cè)趯?duì)倉庫進(jìn)行改動(dòng)過后可以觸發(fā)一個(gè)我們指定的服務(wù)，然后執(zhí)行相應(yīng)的動(dòng)作。

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

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

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

配置 Webhook

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

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

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

再點(diǎn)擊下面的Add webhook 按鈕保存即可。

部署接口服務(wù)

我們?cè)趧倓偛渴鹆?gitbook 的服務(wù)器上面創(chuàng)建一個(gè)名為 webhook 的文件夾，在文件夾里面我們創(chuàng)建三個(gè)文件，分別是index.js，package.json，auto_build.sh

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

var http = require('http');
var spawn = require('child_process').spawn;
# 導(dǎo)入 Gitlab 的 webhook
var 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}`);
    });
}

簡(jiǎn)單介紹一下上面的 JS 代碼，創(chuàng)建一個(gè)服務(wù)監(jiān)聽 6666 端口，提供一個(gè)名叫 autobuild 的接口，在收到 push 操作的時(shí)候就執(zhí)行/root/webhook/auto_build.sh 路徑下的腳本。

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

#! /bin/bash
SITE_PATH='/root/test-doc'
#USER='admin'
#USERGROUP='admin'
cd $SITE_PATH
#git reset --hard origin/master
#git clean -f
git pull
# 切換到 dev 分支，可以自己設(shè)定
git checkout dev
# 啟動(dòng) gitbook
nohup 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"
  }
}

啟動(dòng)服務(wù)器之前，先執(zhí)行npm install 安裝依賴，然后執(zhí)行nohup node index.js &，啟動(dòng)成功過后我們就可以進(jìn)行文檔修改然后 push 到Gitlab 上面，觀察是否及時(shí)更新。這里注意一個(gè)點(diǎn)，我們的腳本里面使用的是 dev 分支，所以要 push 到 dev 分支。

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

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

Tips

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

{
    "title": "XXXX對(duì)接API",
    "description": "這是 Gitbook 與 Gitlab Webhook 集成的項(xiàng)目",
    "author": "Java 極客技術(shù)",
    "plugins": ["splitter","tbfed-pagefooter","expandable-chapters-small"],
    "pluginsConfig": {
    "tbfed-pagefooter": {
        "copyright":"Copyright &copy COOCAA",
        "modify_label": "該文件修訂時(shí)間：",
        "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    },
    "styles": {
        "website": "./customStyle.css"
    }

styles 下面可以增加我們自己寫的樣式，如果需要的話可以加入。

總結(jié)

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

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容