摘要：資源描述我們可以用的語法在名稱的后面加上包含名稱的說明。是指當服務器收到一個請求時候的響應。在中應該有一個狀態(tài)碼和數(shù)據(jù)。在這里我們定義最常見的狀態(tài)碼，表示請求成功。下文將介紹生成高大上的文檔
1、資源Resource
# Gist Fox API Root [/]
在Blueprint里，所有的數(shù)據(jù)信息都是資源(resource)，比如用戶、視頻、文章。
resource的定義以#開始，中間是resource的名稱，最后是用中括號包圍的路徑(URI)，需要注意的是URI是放在[]中的。URI是相對路徑，在這里它就是個/。
2、資源描述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是說明。
3、行為Action
## Retrieve Entry Point [GET]
行為action是一個HTTP請求的屬性之一，在發(fā)送請求的時候會隨數(shù)據(jù)一起發(fā)送到服務器。
我們在這里定義了一個action叫做Retrieve Entry Point (索引入口)，它是一個GET類型的請求。我們可以在后面加上一些描述，
但是因為這個action的名字(Retrieve Entry Point)已經(jīng)把這個行為解釋的很清楚了，所以我們就跳過了這一步。
4、在Blueprint有以下四種action：
- GET ： 獲取數(shù)據(jù)
- POST ： 添加數(shù)據(jù)
- PUT ： 更新數(shù)據(jù)
- DELETE ： 刪除數(shù)據(jù)
5、回應Response
+ Response 200
在API Blueprint中一個action應該至少包括一個回應(response)。response是指當服務器收到一個請求(request)時候的響應。
在response中應該有一個狀態(tài)碼status code和數(shù)據(jù)payload。
在這里我們定義最常見的狀態(tài)碼：200，表示請求成功。
6、響應負載Response Payload
+ Response 200 (application/hal+json)
+ Headers
Link: ;rel="self",;rel="gists"
+ Body
{
"_links": {
"self": { "href": "/" },
"gists": { "href": "/gists?{since}", "templated": true }
}
}
一個響應(response)經(jīng)常包含一些負載(payload)。一個負載(payload)通常包含負載體(body)和負載頭(header)兩個部分。
在這個例子中，我們采用application/hal+json類型作為返回數(shù)據(jù)的類型。
7、URI模板URI Template
## Gist [/gists/{id}]
在URI中的變量需要遵守URI的模板格式，在這個例子中，Gist的編號(id)在URI中就是{id}。
8、URI參數(shù)URI Parameters
+ Parameters
+ id (string) ... ID of the Gist in the form of a hash.
這個id變量是這個resource中的一個參數(shù)(parameter)，我們定義它的類型為string，并且在后面加上一些解釋。
9、資源模型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: ;rel="self", ;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一模一樣的結(jié)構(gòu)。
在前面的例子中，還包含了一個額外的描述，也就是在+ Model和+ Headers中間的那部分內(nèi)容。
ps:下文將介紹aglio生成高大上的api文檔
文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請注明本文地址：http://specialneedsforspecialkids.com/yun/53971.html
