UD5工具箱
使用教程
第一步：了解 API Blueprint 基础语法
API Blueprint 是一种基于 Markdown 的 API 描述语言。一个基本的 API Blueprint 文档由以下部分组成：第一行是元数据行，以井号开头，后面跟着 API 的名称；接下来是简介段落，描述 API 的功能；然后使用 HOST 关键字指定 API 的基础 URL；之后是资源定义，每个资源使用两级标题（## 路径）定义路径，三级标题（### 方法）定义 HTTP 方法。每个端点下可以定义请求（Request）和响应（Response），包括状态码、请求头、请求体和响应体。理解这些基本结构是编写 API Blueprint 文档的基础。
第二步：加载示例文档
点击工具栏的"加载示例"按钮，工具会自动加载一个完整的 API Blueprint 示例文档。示例定义了一个简单的 API，涵盖了核心语法和常用功能。仔细阅读左侧的源码，对照右侧的渲染效果，理解各部分的含义和写法。特别关注元数据的写法、资源和端点的层级结构、请求和响应的定义方式、以及 MSON 数据结构的使用方法。通过学习示例，你可以快速掌握 API Blueprint 的核心语法。
第三步：编写 API 元数据
文档的第一部分是 API 元数据。使用一级标题（#）定义 API 名称，格式为 # API 名称。紧接着写一段简介，描述 API 的整体功能和用途。如果需要指定基础 HOST，使用 HOST 关键字，格式为 HOST: https://api.example.com。元数据部分为整个 API 文档提供上下文信息，帮助读者快速了解 API 的基本情况。示例：# 博客 API HOST: https://api.example.com 一个简单的博客 API，提供文章的增删改查功能。
第四步：定义资源和端点
资源是 API Blueprint 中的核心概念，对应 API 中的一组相关操作。使用二级标题（##）定义资源路径，如 ## 文章列表 (/articles)。在资源下，使用三级标题（###）定义具体的端点操作，如 ### 获取文章列表 GET。每个端点可以包含以下子部分：+ Request（请求定义）、+ Response 200（成功响应）、+ Response 404（错误响应）等。请求和响应使用缩进的 Markdown 列表语法组织，支持描述文本、请求头（Headers）、请求体（Body）和 Schema 等子部分。
第五步：编写请求和响应示例
在端点定义中，使用 + Request 和 + Response 关键字定义请求和响应示例。请求定义可以包含请求头（+ Headers）和请求体（+ Body）。响应定义包含状态码、响应头和响应体。在 Body 中，可以直接写入示例数据，API Blueprint 会将其作为代码块渲染。例如：+ Response 200 (application/json) { "id": 1, "title": "Hello World" }。建议为每个端点定义至少一个成功响应和一个错误响应，以便前端开发者了解 API 的各种返回情况。
第六步：定义数据结构
API Blueprint 支持使用 MSON（Markdown Syntax for Object Notation）定义可复用的数据结构。数据结构定义使用 + Model 关键字，格式为 + 数据结构名称（类型）。例如，定义一个文章数据结构：+ 文章（对象） + id: 1（数字） + title: Hello World（字符串） + content: 这是文章内容（字符串）。定义好的数据结构可以在多个端点中通过引用使用，避免重复定义。MSON 支持多种数据类型，包括字符串、数字、布尔值、对象、数组等。
第七步：预览和导出
编写完成后，检查右侧预览区域的渲染效果。确保所有端点、请求、响应和数据结构都正确显示。如果发现渲染异常，检查源码中的语法是否正确，特别是标题层级、缩进和关键字拼写。确认无误后，可以使用复制源码功能保存 API Blueprint 源码，或使用复制 HTML 功能获取渲染后的 HTML 文档。将 HTML 粘贴到文档平台或博客中，即可分享给团队成员或对外发布。
实用技巧
技巧一：保持缩进一致性。API Blueprint 使用缩进来组织层级关系，建议统一使用四个空格的缩进。技巧二：使用代码围栏标记。在 Body 和 Schema 中使用三个反引号包裹示例数据，确保代码块正确渲染。技巧三：为端点添加描述文本。在端点标题和请求/响应之间添加描述段落，说明端点的功能和使用场景。技巧四：使用 Group 关键字分组。对于大型 API，可以使用 Group 关键字将相关资源分组，提高文档的可读性。技巧五：定期预览。编写过程中频繁查看右侧预览，及时发现和修正语法问题。