一文教會你如何在內網搭建一套屬於自己小組的線上 API 文檔？

来源:https://www.cnblogs.com/zi-you/archive/2022/12/03/16947333.html
-Advertisement-
Play Games

Hello，大家好，我是阿粉，對接文檔是每個開發人員不可避免都要寫的，友好的文檔可以大大的提升工作效率。 阿粉最近將項目的文檔基於 Gitbook 和 Gitlab 的 Webhook 功能的在內網部署了一套實時的，使用起來特方便了。跟著阿粉的步驟，教你部署自己的文檔服務。 步驟 安裝 Node 和 ...


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

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

步驟

  1. 安裝 Node 和 NPM；
  2. 安裝 git， gitbook，gitbook-cli；
  3. 配置 Gitlab Webhook；
  4. 創建 Webhook 監聽服務；
  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/
# 創建軟連接
ln -s /usr/local/node/bin/* /usr/sbin/
# 檢查版本
node -v
# 正常輸出，下麵內容說明安裝成功
> v9.10.1

正常安裝完 Node 過後 NPM 會自動安裝，通過npm -v 可以看到 NPM 的版本號。

Gitbook

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

# 安裝 Gitbook
npm install -g gitbook
# 安裝 Gitbook 命令行工具
npm install -g gitbook-cli
# 創建軟連接
ln -s /usr/local/node/bin/gitbook /usr/sbin/gitbook
# 查看 Gitbook 版本 註意大寫的 V
 gitbook -V

安裝完 Gitbook 過後，我們這個時候就可以部署服務了，我們先創建一個空文件夾 test-doc，然後進入文件夾執行gitbook init 命令，執行成功過後，我們可以看到生成了兩個文件，分別是 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

創建完成過後，我們在 test-doc 目錄下執行命令 gitbook serve 可以看到如下日誌內容

我們訪問伺服器的 4000 埠，正常可以看到如下頁面。

如果沒有看到上面的內容或者訪問不了 4000 埠，我們需要檢查一下伺服器的防火牆，先看下防火牆開放的埠，執行命令 firewall-cmd --list-ports 看看是否開放了 4000 埠，如果沒有執行下麵命令 firewall-cmd --zone=public --add-port=4000/tcp --permanent 將 4000 埠進行開放，然後重新 reload，firewall-cmd --reload ，再次刷新瀏覽器即可。

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

Gitlab Webhook

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

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

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

實現上面的需求，我們需要兩步，第一步在 Gitlab 對應的倉庫裡面設置 Webhook ，也就是每次執行 push 動作後需要調用的服務地址；第二步我們需要一個服務，這個服務需要提供一個介面，當被調用的時候執行拉取最新文檔和重啟 gitbook 服務的功能。

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

配置 Webhook

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

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

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

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

部署介面服務

我們在剛剛部署了 gitbook 的伺服器上面創建一個名為 webhook 的文件夾，在文件夾裡面我們創建三個文件，分別是 index.js，package.json，auto_build.sh

index.js 內容如下：這裡我們的介面名字和 secret需要跟在 Gitlab 上面配置的一樣

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

簡單介紹一下上面的 JS 代碼，創建一個服務監聽 6666 埠，提供一個名叫 autobuild 的介面，在收到 push 操作的時候就執行/root/webhook/auto_build.sh 路徑下的腳本。

auto_build.sh 腳本的內容如下：

#! /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 分支，可以自己設定
git checkout dev
# 啟動 gitbook
nohup gitbook serve > /dev/null 2>&1 &
#chown -R $USER:$USERGROUP $SITE_PATH

腳本裡面主要就是拉取這新的內容，然後切換到 dev 分支，再執行gitbook serve 命令，採用的是nohup gitbook serve > /dev/null 2>&1 &

package.json的內容如下：

{
  "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"
  }
}

啟動伺服器之前，先執行npm install 安裝依賴，然後執行nohup node index.js &，啟動成功過後我們就可以進行文檔修改然後 push 到Gitlab 上面，觀察是否及時更新。這裡註意一個點，我們的腳本裡面使用的是 dev 分支，所以要 push 到 dev 分支。

我們可以在 Gitlab 的 Webhook 下麵看到我們 push 過後觸發的詳情，可以看到是否成功。這裡如果不成功，我們再檢查下防火牆是否開啟了 6666 埠，沒有的話，按照上面的操作開啟即可。

到這裡我們整個基於 Gitbook 和 Gitlab Webhook 實現文檔實時更新的效果就達成了，後續在使用的時候，我們只需要修改內容，然後 push 到對應的倉庫，然後在網站上就能看到最新的修改，大家感興趣可以自己試試哦。

Tips

Gitbook 可以支持插件以及自定義樣式，我們只需要在 test-doc 目錄下麵，創建一個名叫 book.json 的文件，可以在這個文件中自定義一些特定的內容，增加了插件，在啟動的時候需要使用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 下麵可以增加我們自己寫的樣式，如果需要的話可以加入。

總結

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


更多優質內容歡迎關註公眾號【Java 極客技術】，我準備了一份面試資料，回覆【bbbb07】免費領取。希望能在這寒冷的日子里，幫助到大家。

本文來自博客園，作者：zi-you，轉載請註明原文鏈接：https://www.cnblogs.com/zi-you/p/16947333.html


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • Golang反射獲取變數類型和值
    如果想直接查看修改部分請跳轉 動手-點擊跳轉 本文基於 ReactiveLoadBalancerClientFilter使用RoundRobinLoadBalancer 灰度發佈 灰度發佈，又稱為金絲雀發佈，是一種新舊版本平滑發佈的方式。在上面可以對同一個API進行兩個版本 的內容，由一部分用戶先行 ...
  • 【Python】筆記：介面：從協議到抽象基類
    S11 介面：從協議到抽象基類 # random.shuffle 就地打亂 from random import shuffle l = list(range(10)) shuffle(l) print(l) shuffle(l) print(l) [0, 6, 3, 2, 4, 8, 5, 7, ...
  • 我的第一個項目(六)：(前後端)密碼校驗
    好家伙, xdm,密碼驗證忘寫了,哈哈 bug展示: 1.登陸沒有密碼驗證 主要體現為,亂輸也能登進去 (小問題) 要是這麼上線估計直接寄了 分析一波密碼校驗怎麼做: 前端輸完用戶名密碼之後,將數據發送到後端處理 後端要做以下幾件事 ①先確認這個用戶名已註冊 ②我們拿著這個用戶名去資料庫中找對應的數 ...
  • Spring Bean的生命周期
    說明: 本文基於Spring-Framework 5.1.x版本講解 概述 說起生命周期, 很多開源框架、中間件的組件都有這個詞，其實就是指組件從創建到銷毀的過程。 那這裡講Spring Bean的生命周期,並不是講Bean是如何創建的, 而是想講下Bean從實例化到銷毀，Spring框架在Bean ...
  • SpringCloud Alibaba(八) - Durid,SpringSecurity,Shiro
    1、Durid 1.1 簡介 Java程式很大一部分要操作資料庫，為了提高性能操作資料庫的時候，又不得不使用資料庫連接池。 Druid 是阿裡巴巴開源平臺上一個資料庫連接池實現，結合了 C3P0、DBCP 等 DB 池的優點，同時加入了日誌監控。 Druid 可以很好的監控 DB 池連接和 SQL ...
  • Vmware Workstation17 安裝centos7(詳細教程)
    1、參考文獻說明 參考博客：https://www.cnblogs.com/dy12138/articles/16799941.html Vmware Workstation pro 17 安裝會比較簡單，基本上點下一步就行了。 新功能介紹和破解碼請見：https://www.ghxi.com/vm ...
  • 鎖 - 分散式鎖工具
    鎖概述 在電腦科學中，鎖是在執行多線程時用於強行限制資源訪問的同步機制，即用於在併發控制中保證對互斥要求的滿足。 鎖相關概念 鎖開銷：完成一個鎖可能額外耗費的資源，比如一個周期所需要的時間，記憶體空間。 鎖競爭：一個線程或進程，要獲取另一個線程或進程所持有的鎖，邊會發生鎖競爭。鎖粒度越小，競爭的可能 ...
  • SpringCloud Alibaba(七) - JWT（JSON Web Token）
    原文鏈接： JWT詳解:https://blog.csdn.net/weixin_45070175/article/details/118559272 1、什麼是JWT 通俗地說，JWT的本質就是一個字元串，它是將用戶信息保存到一個Json字元串中，然後進行編碼後得到一個JWT token，並且這個 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類