Dev

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
10
+ 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。形成如下的图表内容:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
## 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关键字:不懂，好像是放在一个属性集群中的。