UD5工具箱
术语表
API Blueprint
API Blueprint 是一种基于 Markdown 的轻量级 API 描述语言，用于以人类可读的方式定义 RESTful API。它使用 Markdown 语法作为基础，添加了特定的关键字和结构来描述 API 的端点、参数、请求、响应和数据结构。API Blueprint 的设计哲学是"文档即规范"，即 API 文档本身就是 API 的规范定义。它支持 Markdown 的所有基础语法（标题、列表、链接、代码块等），并扩展了资源、端点、请求、响应、模型等 API 相关的概念。API Blueprint 文档以 .apib 为扩展名，可以被多种工具解析和渲染。
MSON
MSON（Markdown Syntax for Object Notation）是 API Blueprint 中用于定义数据结构的语法。它基于 Markdown 列表语法，以简洁的方式描述 JSON 数据结构。MSON 支持定义对象（属性列表）、数组（元素列表）、字符串、数字、布尔值等基本类型，以及类型属性（如 required、optional、default 等）。例如，一个文章对象可以定义为：+ id: 1（数字，必填）、+ title: Hello（字符串，必填）、+ content: 文本（字符串，可选）。MSON 的优势在于它与 Markdown 语法一致，编写和阅读都很自然，同时可以被工具解析为 JSON Schema 用于验证。
Drafter.js
Drafter.js 是 API Blueprint 官方维护的 JavaScript 解析库，用于将 API Blueprint 源码解析为结构化的 JSON AST（抽象语法树）。它是 C++ 实现的 drafter 解析器的 JavaScript 移植版本，通过 Emscripten 编译为 WebAssembly 或 JavaScript。Drafter.js 支持 API Blueprint 的所有核心语法，包括元数据、资源组、资源、端点、动作、请求/响应、Headers、Body、Schema 和 MSON 数据结构。解析结果是一个嵌套的 JSON 对象，包含了源码的完整结构信息，可以被渲染器转换为 HTML 或其他格式的输出。
资源（Resource）
在 API Blueprint 中，资源对应 API 中的一个实体或概念，通常以 URL 路径表示。资源定义使用二级标题（##），路径可以写在标题后面或下方。例如，## 文章列表 (/articles) 定义了一个文章资源，路径为 /articles。一个资源可以包含多个端点操作（如 GET、POST、PUT、DELETE），这些操作以三级标题（###）定义在资源下。资源是组织 API 文档的核心层级，它将相关的端点分组在一起，形成清晰的文档结构。资源可以有描述文本，说明该资源的用途和特性。
端点（Endpoint）
端点是 API Blueprint 中的一个具体操作，对应 HTTP 方法和路径的组合。端点定义使用三级标题（###），格式为 ### 操作名称 HTTP方法。例如，### 获取文章 GET 定义了一个 GET 端点。端点下可以包含请求定义（Request）、响应定义（Response）、描述文本等子部分。端点是 API 文档中最细粒度的描述单元，它详细说明了客户端如何与服务器交互。每个端点应该明确描述其功能、参数、请求格式和各种可能的响应。
资源组（Resource Group）
资源组是 API Blueprint 中用于将相关资源组织在一起的容器。资源组定义使用一级标题（# Group），格式为 # Group 资源组名称。在资源组下，可以定义多个资源（二级标题）。资源组主要用于文档的逻辑组织，将功能相关的资源归类到同一个组中，提高文档的可读性和可维护性。例如，可以将所有与用户相关的资源（注册、登录、获取信息等）归入"用户管理"组，将所有与文章相关的资源归入"文章管理"组。资源组不直接影响 API 的行为，只影响文档的组织结构。
请求（Request）
请求是 API Blueprint 中描述客户端发送给服务器的数据的部分。请求定义使用 + Request 关键字，可以包含描述文本、请求头（+ Headers）和请求体（+ Body）。请求定义通常放在端点下，描述该端点期望接收的请求格式。请求可以有名称，用于区分不同类型的请求（如 + Request 创建文章请求）。在 Body 中，可以使用代码围栏包裹示例数据，格式为 JSON、XML 或其他格式。请求定义帮助前端开发者了解如何正确构造请求，也是自动化测试的重要参考。
响应（Response）
响应是 API Blueprint 中描述服务器返回给客户端的数据的部分。响应定义使用 + Response 关键字，后面跟着 HTTP 状态码，格式为 + Response 200。响应可以包含描述文本、响应头（+ Headers）和响应体（+ Body）。建议为每个端点定义多个响应，覆盖各种可能的情况（成功、错误、认证失败等）。响应定义帮助前端开发者了解 API 的返回格式，也是 API 文档中最重要的信息之一。在 Body 中使用代码围栏包裹示例响应数据，让读者直观地了解响应的结构和内容。
Body
Body 是 API Blueprint 中描述请求或响应的主体内容的部分。在请求定义中，+ Body 描述客户端发送的数据；在响应定义中，+ Body 描述服务器返回的数据。Body 的内容通常使用代码围栏（三个反引号）包裹，指明数据格式（如 json）。Body 中的内容应该是完整的、可直接使用的示例数据，而不是抽象的类型描述。例如，定义一个文章的响应 Body 时，应该包含完整的文章 JSON 对象，包括 id、title、content、created_at 等字段和具体的示例值。
Schema
Schema 是 API Blueprint 中用于描述数据结构的字段。与 Body 提供具体示例不同，Schema 提供的是抽象的数据结构定义，类似于 JSON Schema。Schema 可以使用 MSON 语法编写，描述请求或响应 Body 的结构、字段类型、必填/可选属性等。Schema 的主要用途是：作为自动化测试的数据验证规则、作为客户端代码生成的数据模型参考、以及作为 API 规范的补充说明。在实践中，Schema 的使用频率低于 Body，但在需要严格数据验证的场景中非常有用。