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