使用API-Blueprint语法来编写API文档

1、资源 Resource

# Gist Fox API Root [/]

在 Blueprint 里，所有的数据信息都是资源(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 请求的属性之一，在发送请求的时候会随数据一起发送到服务器。我们在这里定义了一个 action 叫做 Retrieve Entry Point (索引入口)，它是一个 GET 类型的请求。我们可以在后面加上一些描述，但是因为这个 action 的名字 (Retrieve Entry Point) 已经把这个行为解释的很清楚了，所以我们就跳过了这一步。

4、在 Blueprint 有以下四种 action：

- GET：获取数据
- POST：添加数据
- PUT：更新数据
- DELETE：删除数据

5、回应 Response

+ Response 200

在 API Blueprint 中一个 action 应该至少包括一个回应 (response)。response 是指当服务器收到一个请求(request) 时候的响应。在 response 中应该有一个状态码 status code 和数据 payload。在这里我们定义最常见的状态码：200，表示请求成功。

6、响应负载 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 类型作为返回数据的类型。

7、URI 模板 URI Template

## Gist [/gists/{id}]

在 URI 中的变量需要遵守 URI 的模板格式，在这个例子中，Gist 的编号 (id) 在 URI 中就是{id}。

8、URI 参数 URI Parameters

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

这个 id 变量是这个 resource 中的一个参数(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: <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 文档