在上一篇 ([apiary][02]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - 工具使用介紹篇) 瞭解了怎麽使用apiary這一個工具來撰寫api的文件之後。

在這一篇將來實際的撰寫看看感覺如何。

之前提到過apiary預設的文件格式是API Blueprint，因此這一篇將來看看API Blueprint怎麽使用，並且看看撰寫起來感覺如何。

定一個Scenario

在往下介紹之前，先來想象某一個情景。

假設今天要建立一個功能是一個很簡單的TODO app，在初期只需要簡單的 Create、Read、Update以及Delete (CRUD) 就可以。

那麽怎麽設計這個API呢？

API Blueprint的基本結構

首先，API Blueprint就是markdown加上一些變形，因此只要會markdown，非常容易上手 (如果是Markdown苦手，這篇最後面有放一個鏈接到一個markdown的cheat sheet可以參考)。

整個 API Blueprint 拆解下來大概有這麽幾個關鍵的部分：

1. Metadata - 主要定義那個版本的API Blueprint
2. API Name 和 Description - API的名稱以及説明
3. Resource Group - 相關的Resource可能放在同一個group裡面
4. Resource - 和某個資源有觀的API
5. Actions - 實際可以被觸發執行的内容

來細部看看每一個部分代表什麽。

FORMAT: 1A
HOST: http://polls.apiblueprint.org/

API Name 和 Description

在 Metadata下面以一個# 為開始的就是 API Name

API Name下面的文字就是Description。

Description 可以用任意markdown的語法 - 包含不同的subheading或者是table

範例：

# TODO 功能API

這是一個 TODO 功能 API的描述文件

## 這是第二段落

可以用Table

|  a |  b |   c|  d | e  |
|---|---|---|---|---|
|  1 | 2  |  3 |  4 |  5 |

最後呈現會是：

Resource Group

如果説有好多個Resource相關，可以把他們Group在一起。

主要差異是在Document呈現那邊，同一個group的會在同一個下面。

Resource Group的使用方式是，用heading符號(#) 然後後面跟著關鍵字 Group。

例如：

# Group 功能1

以下為功能1相關的服務

在Documentation看起來選單就會多一層：

如果沒有設定任何Resource Group，那麽大家都是在同一個預設的Resource Group裡面。

## Todo API [/api/todo]

### 取得所有的ToDo [GET]

### 取得單筆TODO [GET /api/todo/{todoId}]

這一篇的完整API Blueprint整個内容如下：

FORMAT: 1A
HOST: http://polls.apiblueprint.org/

# TODO 功能API

這是一個 TODO 功能 API的描述文件

## 這是第二段落

可以用Table

|  a |  b |   c|  d | e  |
|---|---|---|---|---|
|  1 | 2  |  3 |  4 |  5 |

# Group 功能1

以下為功能1相關的服務

## Todo API [/api/todo]

### 取得所有的ToDo [GET]

### 取得單筆TODO [GET /api/todo/{todoId}]

取得單筆todo資料

結語

這篇介紹完了API Blueprint的幾個主要架構項目，不過漏掉了怎麽定義Actions的部分。

由於Actions是文件的核心，也牽扯到request以及response的内容，因此這個部分將會在下一篇介紹。

在下一篇([apiary][04]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - API Blueprint Actions格式篇)，將會針對Actions裡面的定義做介紹，包含了怎麽定義網址的參數，定義傳入的内容以及得到的結果格式等。

參考資料

API Blueprint官方tutorial

這邊有完整的spec以及tutorial可以參考：https://apiblueprint.org/documentation/tutorial.html

Github的Mastering Markdown

如果Markdown不熟悉，那麽可以參考github整理的一個小抄：https://guides.github.com/features/mastering-markdown/