Ubuntu 裡使用 Slate 打造漂亮的 API 文件

Slate 是一個可以用 Markdown 寫作並生成 API 說明文件的工具，由於預設的佈景主題很漂亮，編輯容易上手，並且可以編譯為靜態 HTML 檔案，網頁載入速度快，因此很受歡迎，Github 上的星星數已經超過了 34k。

底下的教學裡我們將給予在 Ubuntu 裡安裝 Slate，並且利用 Nginx 設定檔提供密碼保護的方法步驟。

安裝 Slate

在 Ubuntu 環境裡輸入下面指令，安裝必要的套件：

$ sudo apt install ruby ruby-dev build-essential libffi-dev zlib1g-dev liblzma-dev nodejs patch

接著您可以依照官網裡的指示，fork 後下載原始碼到自己的主機：

1. Fork Github 上的 Slate
2. 利用 git clone https://github.com/YOURUSERNAME/slate.git 將 forked 的專案下載到自己的硬碟
3. cd slate
4. 安裝 slate 需要的相關 ruby 套件

# either run this to run locally
$ bundle install

附註：由於 forked 的專案在 Github 上無法設定為 private。所以筆者是下載原始專案後，rm -rf .git 移除掉 git 相關設定，再於 Github 建立自己私人專案，然後上傳到這私人專案裡。

編輯 Slate

編輯 source/index.md 即可改變文件內容。Slate 支援許多 Markdown 語法，如果您已經很熟悉 Markdown 了，可以直接從檔案下手。

運作 Slate

在本機裡，您可以輸入底下指令以運行 slate

$ bundle exec middleman server

接著移至 http://localhost:4567 即可看到 Slate API 畫面。

而在正式環境裡，原作者強調絕不要使用 Middleman，而是建議編譯為靜態文件後透過服務器傳遞給瀏覽器端的讀者。

輸入底下指令讓文件編譯為靜態檔，整個網站的靜態 HTML 文件會放在 build 資料夾裡。

$ bundle exec middleman build --clean

接著我們需要設定反向代理服務器，好讓外部的互叫能得到回應。

一個可運作的 Nginx 的範例設定檔如底下所示，其中 root 的路徑與 server_name 請更換為您正確的數值，完畢後重啟 Nginx 服務器。在 DNS 設定正確情況下，打開瀏覽器前往 api.yourwebsite.com 就會看到 API 文件了。

server {
   listen       80;
   server_name  api.yourwebsite.com;
   root /home/ubuntu/apps/your-api-doc/build;
}

重新啟動 Nginx

$ sudo service nginx restart

利用 Nginx auth basic 密碼保護文件

有些時候我們不希望將 API 文件對外公開，這時候可以用 Nginx 的密碼設定保護文件。

利用 htpasswd 附帶 -c 標誌建立密碼檔案，我們假定登入的用戶名稱為 tom

$ sudo htpasswd -c /etc/apache2/.htpasswd tom

如果未來要加入更多的用戶，比如 alice，方法相同只是不需要 -c 標誌。

$ sudo htpasswd  /etc/apache2/.htpasswd alice

您可以用 cat 指令檢視文件，確認帳號密碼是否已經加密並記錄起來了

$ cat /etc/apache2/.htpasswd
tom:$apr1$/woC1jnP$KAh0SsVn5qeSMjTtn0E9Q0
alice:$apr1$QdR8fNLT$vbCEEzDj7LyqCMyNpSoBh/

接著我們新增 auth_basic 與 auth_basic_user_file 以添加密碼文件，完成保護的機制。 如果是想要用 IP 位置來限制的話，也很容易，只要指名路徑後，使用 deny, allow 等語法即可。

server {
   listen       80;
   server_name  api.yourwebsite.com;
   root /home/ubuntu/apps/your-api-doc/build;

   # limit access to the whole website
   auth_basic           "Administrator's Area";
   auth_basic_user_file /etc/apache2/.htpasswd;

  location /api {
    #...
    deny  192.168.1.2;
    allow 192.168.1.1/24;
    allow 127.0.0.1;
    deny  all;
  }
}

然後重啟 Nginx 服務器，重新打開瀏覽器連結至畫面，就會看到需要帳號密碼驗證的對話框了。

$ sudo service nginx restart