[Tools] 撰寫 API 工具：Slate 安裝與使用(windows)
最近一直看到很多人在討論 slate，手上剛好有點空檔，就來摸摸看slate 是一個可以用 md 撰寫 API 文件的輕量級工具，是用 ruby 執行，支援 Linux or macOS，不支援 windows，官方文件是說 windows 可能可以跑，但是不支援，不過我是跑起來了，打包後是靜態的 html 檔案，也可以推上 github
使用上除了保留 md 的單頁 link 功能之外，中間和右側的內容是同步滑動的，預設出的版面還會開啟內建的搜尋功能，還有很多人蠻喜歡的 import 另一支 md 文件的功能。
Outline:
1. Install
2. Intro
3. Demo
4. Build / DeployInstall
前往 slate github 後，把這個 repo fork 到自己的空間，接下來 clone 進自己的電腦
- 執行 slate 需要安裝 ruby，windows 安裝這邊
- 還需要安裝 bundler：
$ gem install bundler都裝好之後，執行官網的指令：
$ bundle install
$ bundle exec middleman server // 第一次安裝好之後，之後每次執行都是跑這段就會看到已經跑起來啦：
Intro
安裝好之後，就可以來看看了，因為 Slate 使用 md 編寫，官網很貼心的在安裝流程後還附上 md 的格式。
我們要寫的檔案，是 /source/index.html.md 這支，點開就可以看到預設的範例：
接下來一一來看這支 md 的內容：
第一大塊大部分是一些設定，對應如下圖：
language_tabs ：API 文件可能寫給使用不同語言的人，所以這邊可以設定需要的語言，整頁右側內容會像是分頁一樣切換，支援的語言清單在這邊
includes ：includes 的內容是另一支 md，他會自動引入在最下面的位置，要引入的 md 要放在 /includes 資料夾下
這邊有官方 wiki 針對 includes 更詳細的說明，有興趣的人可以刷刷
search ：是一個內建的搜尋功能，true/false 開啟關閉
> ：右側的說明文字
```語言 … ``` ：剛剛設定的所需語言的 code block，在上方的語言分頁切換
```ruby
# This is some Ruby
```
```python
# This is some Python
```H2 與 code block 生成位置：
code block 會生在上一個內文的下方，以上圖來看， ##Get All Kittens 下面是 ruby 的 code block，所以執行起來可以看到 code block 就在這個 h2 Get All Kittens 的下方：
H3 — api 說明方式和參數表格
這邊的寫法就如 md 的格式一樣，可以寫這個 api 的方法，和參數及說明
Response JSON
response 的 json 也可以用剛剛的 code block 方式寫：
aside 提示說明文字
有底色的說明文字是 aside ，有3種可以使用：
- notice: 藍底提醒
<aside class="notice">You must replace <code>meowmeowmeow</code> with your personal API key.</aside>
2. success: 綠底成功
<aside class="success">Remember — a happy kitten is an authenticated kitten!</aside>
3. warning: 紅底警告
<aside class="warning">Inside HTML code blocks like this one, you can't use Markdown, so use <code><code></code> blocks to denote code.</aside>
大致的說明差不多到這邊，下面來試著寫一個簡易的 api 看看
Usage
現在試著來寫一個簡易的 GET 試試看，
URL: http://example.com/myapi/getInfo
Headers: Content-Type: application/json
Response 200:
{
"active": false,
"name": "emma",
"age": 18,
"info": {
"cell": "0912356789",
"gender": "female"
}
}Description: Get member’s information
我把 index.html.md 的內容清空，只留下第一大段的設定，把 users 這一類的 api 用 includes 的方式另外寫一支再插入，只使用 javascript 這個語言，設定 api 的 base url 是 myapi：
另外在 /includes 資料夾中新增我要寫會員類的 _users.md ，
給一個大標：
# Users第一支 api 名稱：
## Get User Info我想要我的 code block 插入在這個 api 名稱的下方，所以接下來插入 js code block：
```javascript...
...```
接著加上這支 api 的說明
Get member's informationMethods：
### HTTP Request`GET /getInfo`
Headers：
### Headers`Content-Type: application/json`
Response：
> The above command returns JSON structured like this:```json
{
...
}
```
Response 回應資料說明
| Parameter | Default | Description |
|-|-|-|
| active | false | If the account has been activated |
...
簡單的 get api 就寫好了。
Build / Deploy
寫好之後，可以發布到 github 上，也可以純粹 build 出一份靜態的 html 檔案就好，要看的人打開這包 html 就可以了。
Build:
$ bundle exec middleman build --clean
如果要部署到 github 上，要先連結自己的 github repo，如果有下載 GitHub Desktop 就先 push 上去，push 之後執行
忘記怎麼設定的話看這邊：VS code+Github 設定
$ deploy.sh稍待一下之後，就會看到剛剛寫的 api 文件上去啦
內容若有任何錯誤，歡迎留言交流指教！ 🐬
