RAML基本语法

最新推荐文章于 2024-09-06 21:35:54 发布

原创

最新推荐文章于 2024-09-06 21:35:54 发布 · 3.3k 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#raml #api设计

RAML是一种人类可读的API设计语言，它提供了简单易用的语法来声明资源和方法。通过traits，可以定义通用方法属性，如过滤、搜索和分页。resourceTypes则用于创建资源模板，简化代码重复。这两种特性增强了API的一致性和灵活性，便于开发者遵循最佳实践。

人类可读的raml语法

开始设计时，首先创建一个包含以下内容的RAML文件：

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

在以上代码中，我们首先声明这是一个RAML规范，它对应RAML 0.8，并声明API的标题、基本URI、以及这个API的版本号。
在RAML中声明资源非常简单，只需使用/resourceName格式。而添加方法也同样便捷，只需引用相应的HTTP谓词即可：

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

/resource1:
  get:
    description: This gets the collection of resource1
  post:
    description: This adds a new item to the collection

RAML让你能够定义多种相应，返回不同的状态码、头信息以及响应体。例如：

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

/resource1:
  get:
    responses:
      200:
        headers:
          cache-control:
            example: |
              public, no-cache, no-store

        body:
          application/json:
            example: |
              {"name":"Michael Stowe"}
          application/xml:
            example: |

最低0.47元/天解锁文章