无需登录 数据私有 本地保存

RAML 在线预览器 - API设计文件可视化

12
0
0
0
RAML 预览器
等待输入
RAML / YAML

在左侧输入 RAML 内容

或点击「加载示例」快速体验

常见问题与知识点

RAML（RESTful API Modeling Language）是一种基于 YAML 的 API 描述语言，用于设计、文档化和测试 RESTful API。它由 MuleSoft 于 2013 年创建，最新版本为 RAML 1.0。RAML 强调可重用性和清晰的层次结构，支持类型系统、traits（特征）、resourceTypes（资源类型）等高级特性，使得 API 设计更加模块化和可维护。

两者都是 API 描述规范，但设计理念不同：
RAML 采用自顶向下的设计思路，强调复用（traits、resourceTypes），使用 YAML 格式，适合 API 设计阶段。它引入了类型系统和库的概念，便于大型项目组织。
OpenAPI（原 Swagger）采用 JSON Schema 进行类型定义，生态更丰富（Swagger UI、Swagger Editor 等），支持 JSON 和 YAML 两种格式，在文档生成和工具链方面更成熟。
选择取决于团队偏好：如果你重视设计复用和 YAML 的简洁性，RAML 是不错的选择；如果你需要丰富的工具生态和社区支持，OpenAPI 更合适。

RAML 1.0 是一次重大升级：引入了强大的数据类型系统（可定义复杂类型、继承、联合类型等）；新增了库（Libraries）机制用于跨文件复用；增强了注解（Annotations）功能；改进了安全方案定义；引入了 overlays 和 extensions 用于 API 的定制扩展。此外，1.0 版本的文件头标识为 #%RAML 1.0，而 0.8 版本使用 #%RAML 0.8。

在 RAML 1.0 中，使用 types 关键字定义数据类型。内置类型包括：string、number、integer、boolean、date-only、datetime、file、array、object 等。你可以通过继承、约束（pattern、minLength、maximum 等）来定义复杂类型。例如：
types:
  User:
    type: object
    properties:
      id: integer
      name: string

所有解析和预览均在您的浏览器本地完成。您的 RAML 内容不会上传到任何服务器，不会经过网络传输，也不会被存储。这是一个纯客户端工具，使用 js-yaml 库在浏览器中解析 YAML，然后动态渲染为可视化界面。您可以放心地使用它预览包含敏感信息的内部 API 文档。

traits（特征）用于定义可复用的行为模式，如分页、过滤、认证等。通过 is 关键字应用到方法上。
resourceTypes（资源类型）用于定义资源的通用模式（如 collection、item），通过 type 关键字应用到资源上。
两者结合使用可以大幅减少重复代码，提高 API 设计的一致性。例如：定义一个 paginated trait 包含 page 和 limit 查询参数，然后在多个 GET 方法中通过 is: [paginated] 引用它。
🔧 相关工具