使用API Blueprint語法來編寫API文檔

一、資源Resource

# Gist Fox API Root [/]

在Blueprint裏，全部的數據信息都是資源(resource)，好比用戶、視頻、文章。
resource的定義以#開始，中間是resource的名稱，最後是用中括號包圍的路徑(URI)，須要注意的是URI是放在[]中的。URI是相對路徑，在這裏它就是個/。

二、資源描述Resource Description

# Gist Fox API Root [/]
Gist Fox API entry point.
This resource does not have any attributes. Instead it offers the initial API

咱們能夠用Markdown的語法在resource名稱的後面加上包含API名稱的說明。
在這裏Gist Fox API是API名稱，entry point是說明。

三、行爲Action

## Retrieve Entry Point [GET]

行爲action是一個HTTP請求的屬性之一，在發送請求的時候會隨數據一塊兒發送到服務器。
咱們在這裏定義了一個action叫作Retrieve Entry Point (索引入口)，它是一個GET類型的請求。咱們能夠在後面加上一些描述，
可是由於這個action的名字(Retrieve Entry Point)已經把這個行爲解釋的很清楚了，因此咱們就跳過了這一步。

四、在Blueprint有如下四種action：

- GET ： 獲取數據
- POST ： 添加數據
- PUT ： 更新數據
- DELETE ： 刪除數據

五、迴應Response

+ Response 200

在API Blueprint中一個action應該至少包括一個迴應(response)。response是指當服務器收到一個請求(request)時候的響應。
在response中應該有一個狀態碼status code和數據payload。
在這裏咱們定義最多見的狀態碼：200，表示請求成功。

六、響應負載Response Payload

+ Response 200 (application/hal+json)
+ Headers
Link: <http:/api.gistfox.com/>;rel="self",<http:/api.gistfox.com/gists>;rel="gists"
+ Body
{
    "_links": {
        "self": { "href": "/" },
        "gists": { "href": "/gists?{since}", "templated": true }
    }
}

一個響應(response)常常包含一些負載(payload)。一個負載(payload)一般包含負載體(body)和負載頭(header)兩個部分。
在這個例子中，咱們採用application/hal+json類型做爲返回數據的類型。

七、URI模板URI Template

## Gist [/gists/{id}]

在URI中的變量須要遵照URI的模板格式，在這個例子中，Gist的編號(id)在URI中就是{id}。

八、URI參數URI Parameters

+ Parameters
+ id (string) ... ID of the Gist in the form of a hash.

這個id變量是這個resource中的一個參數(parameter)，咱們定義它的類型爲string，而且在後面加上一些解釋。

九、資源模型Resource Model

+ Model (application/hal+json)
HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.
+ Headers
Link: <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"
+ Body
{
    "_links": {
        "self": { "href": "/gists/42" },
        "star": { "href": "/gists/42/star" },
    },
    "id": "42",
    "created_at": "2014-04-14T02:15:15Z",
    "description": "Description of Gist",
    "content": "String contents"
}

資源模型Resource Model是前面定義的資源的一個樣例，它能夠在任何一個request或者response須要的位置引用，一個資源模型有着和前面所說的payload如出一轍的結構。
在前面的例子中，還包含了一個額外的描述，也就是在+ Model和+ Headers中間的那部份內容。

ps:下文將介紹aglio生成高大上的api文檔