其他分享
首页 > 其他分享> > icode9教会你如何在内网搭建一套属于自己小组的在线 API 文档!

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

作者:互联网

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

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

步骤

  1. 安装 Node 和 NPM
  2. 安装 git, gitbookgitbook-cli
  3. 配置 Gitlab Webhook
  4. 创建 Webhook 监听服务;
  5. 编辑文档检查实时更新;

安装 NodeNPM

第一步我们先安装 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 端口进行开放,然后重新 reloadfirewall-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 脚本即可。

标签:icode9,Gitbook,部署,文档服务,安装,防火墙
来源: