API Blueprint​​ 是一种基于 ​​Markdown​​ 的轻量级 API 描述语言

API Blueprint 是一种基于 Markdown 的轻量级 API 描述语言，用于设计、文档化和模拟 RESTful API。它通过简单的文本格式定义 API 的端点、请求/响应结构和示例，适合开发者快速编写和共享 API 规范。以下是详细说明和示例：

---

1. API Blueprint 核心特点
• 基于 Markdown：易读易写，无需复杂工具。

• 机器可解析：支持生成文档、Mock 服务或客户端代码。

• 工具链支持：

• Apiary：在线编辑和托管 API Blueprint。

• Drakov：根据文档生成 Mock 服务。

• Snowboard：渲染为 HTML 文档。

---

2. 基础语法结构

语法	作用	示例
#	API 名称	# 用户管理系统
##	资源分组（如端点集合）	## 用户 [/users]
###	具体 HTTP 方法（GET/POST 等）	### 获取用户 [GET]
+ Request	定义请求（参数、Headers、Body）	+ Headers: Authorization
+ Response	定义响应（状态码、Body 示例）	+ 200 (application/json)

---

3. 实际示例
示例 1：简单的用户 API

# 用户管理系统

## 用户 [/users]

### 获取所有用户 [GET]
+ Response 200 (application/json)
    ```json
    [
        { "id": 1, "name": "John" },
        { "id": 2, "name": "Jane" }
    ]
    ```

### 创建用户 [POST]
+ Request (application/json)
    ```json
    { "name": "Alice" }
    ```

+ Response 201 (application/json)
    ```json
    { "id": 3, "name": "Alice" }
    ```

## 单个用户 [/users/{id}]

### 获取用户详情 [GET]
+ Parameters
    + id (number) - 用户ID

+ Response 200 (application/json)
    ```json
    { "id": 1, "name": "John" }
    ```

+ Response 404 (text/plain)
    ```text
    User not found
    ```

---

示例 2：带认证的订单 API

# 电商订单系统

## 订单 [/orders]

### 获取订单列表 [GET]
+ Headers
    Authorization: Bearer {token}

+ Response 200 (application/json)
    ```json
    [
        { "id": "ORD-001", "total": 99.99 },
        { "id": "ORD-002", "total": 149.99 }
    ]
    ```

### 提交订单 [POST]
+ Request (application/json)
    ```json
    {
        "items": [
            { "productId": 101, "quantity": 2 }
        ]
    }
    ```

+ Response 201 (application/json)
    ```json
    { "orderId": "ORD-003", "status": "processing" }
    ```

---

4. 工具链应用示例
(1) 使用 Apiary 在线渲染

1. 将上述 Markdown 粘贴到 Apiary。
2. 自动生成交互式文档，支持直接测试 API。

(2) 使用 Drakov 启动 Mock 服务

# 安装 Drakov
npm install -g drakov

# 启动 Mock 服务（假设文件为 api.md）
drakov -f api.md -p 8080

访问 http://localhost:8080/users 将返回示例中的 JSON 数据。

(3) 生成 HTML 文档

# 安装 Snowboard
npm install -g snowboard

# 生成 HTML
snowboard html api.md -o output/

---

5. 对比其他描述语言

特性	API Blueprint	OpenAPI (Swagger)	RAML
语法	Markdown	YAML/JSON	YAML
学习曲线	低（适合快速编写）	中（结构复杂）	中
Mock 支持	通过 Drakov	通过 Swagger UI	通过 RAML Mock
代码生成	有限（需第三方工具）	完善（官方工具链）	支持

---

6. 适用场景
• 快速原型设计：用 Markdown 快速描述 API 并与团队共享。

• 前后端协作：前端开发者根据 Mock 服务提前开发。

• 轻量级文档：无需复杂配置，直接托管在 Git 仓库中。

---

总结
API Blueprint 通过 简洁的 Markdown 语法 和 丰富的工具链，为 RESTful API 设计提供了灵活高效的解决方案。适合中小型项目或敏捷开发团队，尤其适合偏好 Markdown 的开发者。