[API]使用Blueprint来高雅的编写接口文档

Blueprint(http://apiary.io/)是apiary公司的工具包，用来编写API文档，类似于Markdown，是一种标记语言。

对于习惯使用RESTful API的同志们来说，使用Blueprint可以快速的写出高雅大气的文档：

下面以一个Github中的Gist服务为例，简单的演示一下Blueprint的应用。

原文地址：http://blog.callmewhy.com/2014/06/05/blueprint-tutorial/

API Blueprint是一套API描述标准，和Markdown一样，属于一种标记语言，可以把标记文稿转换成漂亮的接口文档。

在这里我们假设开发一个关于Gist的接口文档：Gist Fox API，以此来学习API Blueprint的全部核心特性。

Gist是一个粘贴工具，用户把内容粘贴后会得到一个URL，通过这个URL可以访问先前粘帖的文本，方便地共享文本或者代码。具体可以参考Github提供的GitHub Gists服务。

我们将在我们的API中提供如下功能：

• 列出所有的Gist
• 搜索一个Gist
• 创建一个Gist
• 编辑已有的Gist
• 给一个Gist星标
• 给一个Gist取消星标
• 检查一个Gist是否星标
• 删除一个Gist

---

1.Gist Fox API

刚开始的时候，我们的Gist Fox API是这样的：

1 2 3 4

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

我们刚刚做了什么？接下来让我们一行一行的来分析一下。

• 元数据Metadata
  

  1	FORMAT: 1A

  
  你需要使用一个元数据(metadata)，来明确指定API Blueprint的版本。
  比如在上述文件中我们使用的版本号是1A。

• 接口名称API Name
  

  1	# Gist Fox API

  
  每一个好的API都应该有一个名字，我们的API也是这样：Gist Fox API，使用Markdown中的#标记表示API的名字。

• 接口描述API Description
  

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

  
  在API的名字后面可以用Markdown的语法加上一些API的解释。

---

2.Markdown

如果要写一个blueprint文档，你唯一需要的就是一个文本编辑器，最好是一个Markdown的文本编辑器，VI和Byword都是不错的选择，在线的文本编辑器也没有任何问题。你甚至可以直接在Github的仓库里编辑bluePrint格式的文档。

如果你完全不知道Markdown，现在是一个学习的好机会。只需要点击Markdown Tutorial就可以开始学习。学完了可别忘了回来看看，我们这里也很精彩！

如果你需要查阅Markdown的语法可以直接点击Gruber’s Original查看。

---

3.First Resource

我们第一个要写的内容是根目录(root)，我们API的入口可以这样定义：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

# 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 Entry Point [GET] + Response 200 (application/hal+json) + Headers Link: <http:/api.gistfox.com/>;