API Blueprint笔记

0 前言

Node还没好好看完，又得开新坑了。

API Blueprint，是一个用于编写web api的规范，采用类似于markdown的语法，语法本身没什么难点，记住几个关键词，也就差不多了。其强大之处在于丰富的工具、插件。

apiaryio提供了实时预览的功能，让书写web api更加便捷和规范，并且可以讲web api文档转换成虚拟的web server，直接提供给前端测试，这样让团队开发耦合度更低，效率也更高。

Blueprint的项目托管在Github上，有比较详细的指导说明。

---

1 使用

Blueprint的书写方式类似markdown，所以对于习惯用markdown写博客的人来说，十分具有亲和力，上手完全没有障碍。

由于内容比较杂，所以我就从例子出发，阐述一下各个关键字的用法，这个例子的完整代码在官方的文档里有，不过我还是复制一遍，方便讲解：

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

## Authentication
*Gist Fox API* uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope.

## Media Types
Where applicable this API uses the [HAL+JSON](https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md) media-type to represent resources states and affordances.

Requests with a message-body are using plain JSON to set or update resource states.

## Error States
The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.

# Gist Fox API Root [/]
Gist Fox API entry point.

This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and
HAL links.

## Retrieve the Entry Point [GET]

+ Response 200 (application/hal+json)
    + Headers

            Link: <http:/api.gistfox.com/>;rel="self",<http:/api.gistfox.com/gists>;rel="gists",<http:/api.gistfox.com/authorization>;rel="authorization"

    + Body

            {
                "_links": {
                    "self": { "href