什么是RAML？

RAML 的全称是 RESTful API Modeling Language，这是一种基于 YAML 1.2 格式的新规范，因此机器与人类都能够轻易地理解其中的内容。但 RAML 的目的不仅仅在于创建更易于理解的规范（你可以将这一工作指派给文档团队，他们会做得更好）而已。RAML 的设计者 Uri Sarid 希望使用者能够打破固有的思维，在开始编写代码之前以一种全新的方式对 API 进行建模。

REST API描述语言之战

在2010年代初的API设计战争中，规范格式与行业主导地位作斗争。当尘埃落定时，三种格式成为有前途的竞争者：API Blueprint、RAML和OpenAPI（前身为Swagger）。

• API Blueprint是一种用于生成文档的标记格式。它于2013年由Apiary开发，然后被甲骨文收购。
• RAML代表RESTful API建模语言，是一种API设计格式，由MuleSoft于2013年开发，然后被Salesforce收购。
• Swagger是一种API描述格式，由Wordnik于2010年开发，然后被SmartBear收购。它后来更名为OpenAPI，并捐赠给Linux基金会。

注：当下事实上的赢家是OpenAPI(Swagger)，原因参考《OpenAPI vs RAML vs API Blueprint》。

怎么使用RAML？

• 设计：RAML使用标准的yaml格式，使用方法参考：RAML 1.0 使用RAML描述API文档信息的一些用法整理，你可以快速的构造你的API，并以人类友好的格式将它呈现出来。它涵盖了一些重要设计的最佳实践，如建模、模式、模板以及代码重用。；
• 构建：一旦设计好你的API，你就可以借助一些开发工具，将设计好的静态API文档，变成一个服务器端来提供服务（mock server）；
• 测试：引入单元测试可以有效地保证API实现的正确性，你可以通过运行一些脚本来测试你服务端是否涵盖了你设计好的API；
• 文档：Raml可以帮助你脱离同步维护一份额外文档的痛苦。RAML是一门API描述语言，所以你的API一旦被描述，它就是一份现成的API文档。你可以借助一些工具将它生成可视化的文档；
• 共享：你可以借助一个基本的JavaScript来生成一些交互式工具（API Consoles或API Nodebooks），这样其他开发者可以使用标准格式与你的维护团队进行交流。

RAML代码示例:

#%RAML 1.0

title: Mobile Order API

baseUri: http://localhost:8081/api

version: 1.0



uses:

  assets: assets.lib.raml



annotationTypes:

  monitoringInterval:

    type: integer



/orders:

  displayName: Orders

  get:

    is: [ assets.paging ]

    (monitoringInterval): 30

    description: Lists all orders of a specific user

    queryParameters:

      userId:

        type: string

        description: use to query all orders of a user

  post:

  /{orderId}:

    get:

      responses:

        200:

          body:

            application/json:

              type: assets.Order

            application/xml:

              type: !include schemas/order.xsd

RAML与OpenAPI：有什么区别？

1. 格式：OpenAPI使用YAML或JSON来设计API，而RAML使用YAML或JSON以及XML扩展来记录API。这种格式的差异允许组织和呈现API文档的方式略有不同。
2. 版本控制：OpenAPI历史悠久，并通过多个版本不断发展，最新的是OpenAPI 3.0。另一方面，RAML在2013年发布了一个重大版本，目前处于1.0版本。版本控制的这种差异会影响每种语言中某些功能的可用性和成熟度。
3. 工具生态系统：与RAML相比，OpenAPI拥有更广泛的工具生态系统。这包括从OpenAPI规范中生成服务器存根、客户端库和文档的广泛工具。RAML的工具生态系统虽然不那么广泛，但仍然为各种任务提供工具，但可用的选项可能更少。
4. 模式定义：OpenAPI使用JSON模式来描述和验证数据模型，而RAML使用一种名为JSON类型语言（JTL）的内置模式定义语言。模式定义的这种差异可能会影响数据模型在API文档中的定义和使用方式。
5. 成熟度和采用：与RAML相比，OpenAPI拥有更大的社区和更广泛的采用。这意味着OpenAPI规范更常被API开发人员、工具提供商和API消费者使用和支持。RAML虽然仍被广泛使用，但社区可能略小，可用资源更少。
6. 可扩展性：OpenAPI提供了一个更可扩展的框架，用于通过使用扩展来添加自定义规范和注释。RAML虽然也支持可扩展性，但在某些领域添加自定义规格的选项可能更有限。

一句话：RAML面向‘设计者、API生产者’，OpenAPI面向‘使用者、API消费者’。

参考资料

RAML.org – RAML规范的官方网站
JSON-schema.org – JSON模式的主页
基于RAML的API接口文档管理
Introduction to RAML