UD5工具箱
常见问题
什么是 API Blueprint？它和 OpenAPI 有什么区别？
API Blueprint 是一种基于 Markdown 的轻量级 API 描述语言，使用 Markdown 语法来定义 API 的端点、参数和响应。OpenAPI（Swagger）则使用 YAML 或 JSON 格式来描述 API。主要区别包括：语法风格不同，API Blueprint 使用 Markdown 的标题和列表语法，更接近自然写作方式；OpenAPI 使用 YAML 的键值对和嵌套结构，更接近数据定义；工具生态不同，OpenAPI 拥有更庞大的工具和插件生态；社区支持不同，OpenAPI 的社区规模更大，文档资源更丰富。选择哪种格式取决于团队的技术栈和偏好，如果团队习惯 Markdown，API Blueprint 是一个不错的选择。
API Blueprint 的核心语法有哪些？
API Blueprint 的核心语法包括：元数据定义（使用一级标题定义 API 名称，HOST 关键字指定基础 URL）；资源定义（使用二级标题定义路径，如 ## 文章列表 (/articles)）；端点定义（使用三级标题定义 HTTP 方法，如 ### 获取文章 GET）；请求定义（使用 + Request 关键字，包含 Headers 和 Body）；响应定义（使用 + Response 加状态码，包含 Headers 和 Body）；数据结构定义（使用 + Model 和 MSON 语法）；资源组（使用 # Group 关键字分组相关资源）。此外还支持描述文本、代码围栏、链接等 Markdown 基础语法。
MSON 是什么？如何使用它定义数据结构？
MSON（Markdown Syntax for Object Notation）是 API Blueprint 中用于定义数据结构的语法。它使用 Markdown 列表语法来描述 JSON 数据结构，格式简洁直观。定义对象时，每个属性占一行，使用缩进表示层级：+ 属性名: 示例值（类型）。例如，定义一个用户对象：+ id: 1（数字，必填）+ name: 张三（字符串，必填）+ email: zhangsan@example.com（字符串，可选）。MSON 支持的数据类型包括：string（字符串）、number（数字）、boolean（布尔值）、object（对象）、array（数组）。类型属性使用圆括号标注，可以包含 required、optional、default 等修饰符。
API Blueprint 支持哪些功能？
API Blueprint 支持的功能包括：定义 API 元数据（名称、描述、版本、基础 URL）；定义资源和端点（HTTP 方法和路径）；定义请求和响应（状态码、请求头、请求体、响应体）；使用 MSON 定义数据结构和模型；定义资源组进行文档组织；使用 Markdown 语法编写描述文本；支持代码围栏显示示例数据；支持链接和图片。API Blueprint 还支持 API 继承和引用机制，可以通过引用其他 API Blueprint 文件来复用定义。此外，API Blueprint 生态系统中有多种工具支持 Mock 服务器、代码生成和测试自动化等功能。
如何将 API Blueprint 文档转换为 HTML 文档？
将 API Blueprint 转换为 HTML 有多种方式：使用本工具的复制 HTML 功能，可以将渲染后的 HTML 文档直接复制到剪贴板，然后粘贴到任何支持 HTML 的平台；使用 Aglio 工具，这是一个命令行工具，可以将 API Blueprint 文件转换为美观的 HTML 文档，支持自定义主题和样式；使用 Snowcrash 解析器，这是 API Blueprint 的 C++ 参考实现，可以将 .apib 文件解析为 JSON AST，然后使用自定义模板渲染为 HTML；使用在线转换服务，一些网站提供 API Blueprint 到 HTML 的在线转换。本工具提供了最便捷的方式，无需安装任何软件即可获得高质量的 HTML 输出。
API Blueprint 支持哪些 HTTP 方法？
API Blueprint 支持所有标准的 HTTP 方法，包括：GET（获取资源）、POST（创建资源）、PUT（完整更新资源）、PATCH（部分更新资源）、DELETE（删除资源）、HEAD（获取响应头）、OPTIONS（获取支持的方法）。在端点定义中，HTTP 方法写在三级标题中，格式为 ### 操作名称 HTTP方法。例如：### 获取文章列表 GET、### 创建文章 POST、### 更新文章 PUT、### 删除文章 DELETE。每个端点可以定义不同的请求和响应，方法名称不区分大小写，但建议使用大写以保持一致性。
API Blueprint 的解析准确性如何？
API Blueprint 的解析准确性取决于解析器的实现。本工具使用 drafter.js，这是 API Blueprint 官方维护的 JavaScript 解析器，基于 C++ 实现的 drafter 编译为 JavaScript。drafter.js 是目前最准确的 JavaScript API Blueprint 解析器，它完整实现了 API Blueprint 规范，能够正确处理各种语法结构。不过，由于 API Blueprint 语法的灵活性，某些边缘情况可能有不同的解析结果。建议遵循 API Blueprint 官方文档的语法规范编写文档，并使用本工具的实时预览功能验证解析结果。如果遇到解析问题，可以参考 API Blueprint 规范或社区讨论获取帮助。
本工具与 Aglio 等命令行工具有什么区别？
本工具和 Aglio 都用于将 API Blueprint 渲染为 HTML，但使用方式和特点不同。本工具是在线 Web 工具，无需安装任何软件，打开浏览器即可使用，适合快速预览和编辑；Aglio 是命令行工具，需要本地安装，适合集成到构建流程和自动化脚本中。本工具提供实时预览，编辑源码时即时看到渲染效果；Aglio 需要手动运行命令生成 HTML 文件。本工具适合临时查看和分享；Aglio 适合生成静态 HTML 文件用于文档站点。本工具使用 drafter.js 作为解析引擎；Aglio 使用 Snowcrash（C++ 实现），解析速度更快。两者可以结合使用：使用本工具进行快速编辑和预览，使用 Aglio 生成最终的文档文件。