一文教会你如何在内网搭建一套属于自己小组的在线 API 文档?

Hello,大家好,我是阿粉,对接文档是每个开发人员不可避免都要写的,友好的文档可以大大的提升工作效率。

阿粉最近将项目的文档基于 GitbookGitlabWebhook 功能的在内网部署了一套实时的,使用起来特方便了。跟着阿粉的步骤,教你部署自己的文档服务。

步骤

  1. 安装 NodeNPM
  2. 安装 gitgitbookgitbook-cli
  3. 配置 Gitlab Webhook
  4. 创建 Webhook 监听服务;
  5. 编辑文档检查实时更新;

安装 NodeNPM

第一步我们先安装 NodeNPM

# 下载压缩包
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 端口进行开放,然后重新 reloadfirewall-cmd --reload ,再次刷新浏览器即可。

后面的操作就是在文档中增加相应的内容即可,当然这里模拟的是本地创建文件夹,如果我们的文档已经存在仓库中,我们可以通过 git 将仓库拉下来,增加 README.mdSUMMARY.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.jspackage.jsonauto_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 分支,所以要 pushdev 分支。

我们可以在 GitlabWebhook 下面看到我们 push 过后触发的详情,可以看到是否成功。这里如果不成功,我们再检查下防火墙是否开启了 6666 端口,没有的话,按照上面的操作开启即可。

到这里我们整个基于 GitbookGitlab 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 下面可以增加我们自己写的样式,如果需要的话可以加入。

总结

今天阿粉给大家分享了一个使用的技能,在工作中搭建起来,相信会很有帮助的。有任何问题欢迎在评论区留言我们一起讨论~,原创不宜,如有帮助欢迎点赞分享,一键三连。

本文由mdnice多平台发布

61 声望
13 粉丝
0 条评论
推荐阅读
手把手教你将 ChatGPT 接入企业微信
之前给大家介绍了如何将 ChatGPT 接入个人微信、钉钉以及知识星球,没看过的小伙伴可以点击链接进去看一下。但是众所周知,接入个人微信是有风险的,官方是不允许我们通过非法的客户端进行登录的。今天给大家分享...

Java极客技术阅读 860

封面图
花了几个月时间把 MySQL 重新巩固了一遍,梳理了一篇几万字 “超硬核” 的保姆式学习教程!(持续更新中~)
MySQL 是最流行的关系型数据库管理系统,在 WEB 应用方面 MySQL 是最好的 RDBMS(Relational Database Management System:关系数据库管理系统)应用软件之一。

民工哥14阅读 1.9k

封面图
终于卷完了!Redis 打怪升级进阶成神之路(2023 最新版)!
是一种非关系型数据库服务,它能解决常规数据库的并发能力,比如传统的数据库的IO与性能的瓶颈,同样它是关系型数据库的一个补充,有着比较好的高效率与高性能。专注于key-value查询的redis、memcached、ttserver。

民工哥10阅读 810

封面图
算法可视化:一文弄懂 10 大排序算法
在本文中,我们将通过动图可视化加文字的形式,循序渐进全面介绍不同类型的算法及其用途(包括原理、优缺点及使用场景)并提供 Python 和 JavaScript 两种语言的示例代码。除此之外,每个算法都会附有一些技术说...

破晓L7阅读 906

封面图
硬卷完了!MongoDB 打怪升级进阶成神之路( 2023 最新版 )!
前面我们学习:MySQL 打怪升级进阶成神之路、Redis 打怪升级进阶成神之路,然后我们还在继续 NoSQL 的卷王之路。从第一篇文章开始,我们逐步详细介绍了 MogoDB 基础概念、安装和最基本的CURD操作、索引和聚合、工...

民工哥6阅读 450

封面图
「刷起来」Go必看的进阶面试题详解
逃逸分析是Go语言中的一项重要优化技术,可以帮助程序减少内存分配和垃圾回收的开销,从而提高程序的性能。下面是一道涉及逃逸分析的面试题及其详解。

王中阳Go4阅读 1.9k评论 1

封面图
架构设计-高性能篇
大家好,我是易安!今天我们谈一谈架构设计中的高性能架构涉及到的底层思想。本文分为缓存架构,单服务器高性能模型,集群下的高性能模型三个部分,内容很干,希望你仔细阅读。

架构狂人4阅读 771

61 声望
13 粉丝
宣传栏