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