API Blueprint Docker

API Blueprint

上次介紹的 API Blueprint 解決方案 雖然不錯，可是有一些問題：

1. 部署麻煩，須要裝很多東西

2. 文檔更新後不支持自動部署

3. 沒有權限控制

以致於咱們團隊最後沒有用這個方案，因此我想了下解決方案。

1. 經過 Docker 鏡像，解決部署問題

2. 經過 Docker 鏡像中的腳本，配合 Github Webhook 來實現自動化部署

3. 還未實現

正好順便學習一下 Docker，Docker 的書看過幾本了，以前同事也作過度享，但仍是那句話：實踐出真知。

以前雖然瞭解各類概念，可是本身搗鼓後，纔算是真正的理解。

 

實現方案

Dockerfile

Dockerfile 很是簡單，直接貼出來就好了：

FROM centos

RUN yum install -y epel-release && yum update -y && yum install -y node npm make nginx git
RUN npm install -g aglio drakov

COPY scripts/startup.sh /usr/local/bin/
COPY scripts/deploy.sh /usr/local/bin/
COPY scripts/webhook.js /usr/local/bin/

RUN chmod -R 755 /usr/local/bin/*

CMD /usr/local/bin/deploy.sh && /usr/local/bin/startup.sh

這裏主要依賴了nodejs和nginx。

aglio只能把文檔渲染成html，可是不包括 server，因此須要配合nginx。

而drakov本身會啓動一個 server。

而後這裏最關鍵的就是3個腳本了，繼續詳解一下這三個腳本。

 

startup.sh

這裏是啓動腳本，看Dockerfile最後一行，定義了默認啓動腳本。

nginx
nohup drakov -f "/opt/api-blueprint/*.apib" --public > /dev/null &
node /usr/local/bin/webhook.js

三行命令對應3個服務。

 

deploy.sh

這個腳本負責拉取新的文檔，並調用aglio渲染成html，而後複製到nginx根目錄。

if [ -d /opt/api-blueprint ]
then
        cd /opt/api-blueprint
        git checkout -f
        git clean -f
        git pull
else
        git clone $repository /opt/api-blueprint
        cd /opt/api-blueprint
fi

find . -name "*.apib" | sed 's/.apib//' | xargs -i -t aglio -i {}.apib --theme-template triple -o {}.html
rm -rf /usr/share/nginx/html/*
cp -R * /usr/share/nginx/html/

 

webhook.js

這個腳本負責監聽 webhook，啓動部署。

var http = require('http');
var exec = require('child_process').exec;

var cmdStr = 'bash -c /usr/local/bin/deploy.sh';

setInterval(function() {
  console.log("Start auto reload.")
  exec(cmdStr, function(err, stdout, stderr) {
    if (err) {
      console.error(err);
    } else {
      console.log("Update success!");
      console.log(stdout);
    }
  });
}, 5 * 60 * 1000);

http.createServer(function(req, res) {
  console.log("Start webhook reload.")
  exec(cmdStr, function(err, stdout, stderr) {
    if (err) {
      console.error(err);
    } else {
      console.log("Update success!");
      console.log(stdout);
    }
  });
  res.writeHead(200, {
    'Content-Type': 'text/plain'
  });
  res.end("");

}).listen(8080);

收到請求就從新調用一下deploy.sh。

Github 上能夠這麼設置：

若是你在內網，不方便暴露到公網，能夠忽略這個功能，腳本內部也是自動刷新，5分鐘一次。

 

如何使用？

這個項目已經放到了 Github 和 Docker Hub 上。

源代碼：https://github.com/dozer47528/api-bluepr...

Docker 鏡像：https://hub.docker.com/r/dozer47528/api-...

使用起來很是簡單：

docker run --name test \
-e "repository=https://github.com/dozer47528/api-blueprint-test.git" \
-p 80:80 -p 8080:8080 -p 3000:3000 \
-d dozer47528/api-blueprint-docker

把其中的repository替換成大家本身的地址便可。

內部端口須要映射一下：

• 80: 文檔

• 8080: webhook

• 3000: Mock 服務器

 

如何支持私有倉庫？

首先在宿主機上配置完ssh，而後在啓動的時候隱射一下文件-v ~/.ssh:/root/.ssh。

完整的命令相似於這樣：

docker run --name test \
-v ~/.ssh:/root/.ssh \
-e "repository=https://github.com/dozer47528/api-blueprint-test.git" \
-p 80:80 -p 8080:8080 -p 3000:3000 \
-d dozer47528/api-blueprint-docker

 

如何修改aglio的啓動參數？

啓動的時候加上這個參數：-e "aglio=--theme-template triple"

完整的命令相似於這樣：

docker run --name test \
-e "aglio=--theme-template triple" \
-e "repository=https://github.com/dozer47528/api-blueprint-test.git" \
-p 80:80 -p 8080:8080 -p 3000:3000 \
-d dozer47528/api-blueprint-docker

aglio的文章文檔在這邊：[https://github.com/danielgtaylor/aglio#e...

 

文檔怎麼寫？

本身的文檔怎麼寫？首先，我這邊只會轉換apib結尾的文檔，這是 API Blueprint 的標準後綴名。

而後你也能夠在裏面直接扔html文件。

全部文檔文件夾隨便放，我會遞歸全部文件。

最後建議放一個index.html，本身作一個導航，這樣本身用起來方便一點。

我這邊有一個例子：

https://github.com/dozer47528/api-bluepr...

 

下一步是什麼？

還有一些不完善的地方須要改進：

• 支持私有倉庫，例如 Bitbucket（已完成）

• 支持自定義aglio樣式，我如今在腳本里寫死了一個我本身比較喜歡的樣式，最好能夠在docker run的時候把樣式傳進去（已完成）

• 有些服務部署在內網，不方便設置 webhook，要支持自動刷新數據（已完成）

 

源地址:http://www.dozer.cc/2016/03/api-blueprin...