API-Blueprint

为了能够写api,研究了API-Blueprint。这里记录一下部分学习经过

API-Blueprint的学习经过

(被折磨的不要不要的。。。)
首先似乎是通用markdown的部分语法的。。。
然而,makrdown里面的部分语法效果有微妙差距。

元数据 metadate

FORMAT: 版本
通过一个元数据来指定当前的版本

Blueprint的标题等级关系

markdown中的
##
表示的是第几级标题,而在API-Blueprinth中会表现呈如下;

可以看到,Blueprint的标题等级并不非常严格,一般来说按照如下的规则:

  • 一级标题表示的就是这个API的总分组(Group)。
  • 二级标题表示的是API中某个组(group)下拥有的方法,也叫行为[action],以及其对应的资源位置。
  • 三级标题为某个模块中的方法细节内容,里面可以写当前方法传输的请求方式以及相应的属性等等,比如对应的request 和 response。
1
2
3
# Group 消息
## 消息 [/messages/{id}]
### 获取消息 [GET]

其中# Group xxx 会产生上图中最上方的黑色框框的效果,表示下列方法都属于这个Group。然后接下来跟在 #后,并且含有[url]的内容将会被当成当前的行为,而包含了[请求方式]的将会被当成上一个出现了[url]的具体方法。

资源(url)

我们可以在一级标题后定义我们的模块资源位置:

1
## 消息 [/messages/{id}]

通过标题 [url] 的形式,可以将我们的模块安排在对应的url下。在Blueprint里面,所有的数据信息都是资源。resource的定义是以#开始的,中间是resource的名字,最后使用[url]将数据包括在里面

Response的细节

response是写在三级标题下的内容。由于算是属于该标题下,所以另启一行使用+作为开头

1
2
3
### 获取消息 [GET]
+ Response 200 (application/json)

当我们谈及一个action的交互的时候,就会谈及response的相关。Blueprint中我们可以记录response的返回状态码和返回内容的类型。
比如:
Response 200 (text/plain)
表示当前的返回值内容为200,同时将Content-Type设置为text/html,从而能够调用html的解析(当然这个状态就是啥都不解析。。)
然后,我们还能够继续其返回头和返回体。设置这些的时候,header和body作为同级别位于对应方法之下,应该使用一个tabs,其具体内容则是要使用三个tabs作为缩进表示为标题的内容

1
2
3
4
5
6
7
### 获取消息 [GET]
+ Request Plain Text Message
+ Headers
Accept: text/plain

(倒是更加符合md的格式了)

Request的细节

Blueprint中,request和response的结构差不多,也可以放相似的内容。只是request使用的是request关键字而已。

参数的加入

当我们想要在二级标题的url下增加参数后,我们就可以通过使用{}将参数包裹,如:

1
## 消息 [/message/{id}]

然后需要在接下的位置上写上id的相应[例子参数][类型][相关叙述]
格式为:
[tabs]+ 变量名: 例子 (类型) - 叙述

1
2
3
+ Parameters
+ id: 2 (number) - a unique identifier of the message

注意空格,不然的话很容易出问题.

我们还可以提供另一个url,返回一系列我们的message。然后这个url下需要加上用于限制返回资源的参数limit,当然由于这个参数可能不会影响每个方法,所以还要在特定的方法下写:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
### Retrieve all Messages [GET]
+ Parameters
+ limit (number, optional) - The maximum number of results to return.
+ Default: `20`
+ Response 200 (application/json)
\[
{
"id": 1,
"message": "Hello World!"
},
{
"id": 2,
"message": "Time is an illusion. Lunchtime doubly so."
},
{
"id": 3,
"message": "So long, and thanks for all the fish."
}
\]

注意json返回值如果是一个list内容的话,至少要两个tabs。

如果设置没问题的话,结果会如上。

属性的增加

当想要在request或者response中增加属性的时候(也就是表单一类的参数值),我们需要首先设置一个Attributes属性,然后在后写上足够的注释:

1
2
3
4
5
6
7
8
9
+ Attributes(object)
+ id: 250ff(string, required)
+ created: 1415203908 (number) - Time stamp
+ percent_off :25 (number)
A positive integer between 1 and 100 that represents the discount the coupon will apply
+ redeem_by (number) - Date after which the coupon can no longer be redeemed

同样还是要注意空格和tabs。形成如下的图表内容:

如果我们已经实现了一个属性,然后在别的对象中也有相同的属性的时候,可以直接填入之前卸写了属性的位置:

## Coupon [/coupons/{id}]  
A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer

+ Parameter

    + id (string)

        The ID of the desired coupon.

+ Attributes(object)

    ... 

### Retrive a Coupen [GET]
Retrives the coupon with the given ID

+ Response 200 (application/json)

    + Attributes(Coupon) <-------------此处直接引用coupon

现在先记一下存疑的地方好了:
array关键字:不懂,好像是放在一个属性集群中的。