RAML 默认信封

Posted 2023-02-19

【中文标题】RAML 默认信封

【英文标题】：RAML default envelope

【发布时间】：2016-02-27 07:11:36

【问题描述】：

我的 API 对所有集合类型资源都有一个默认信封，如下所示：

  "data": [,,],
  "self": "http://api-url/members",
  "total": 120,
  "limit": 10,
  "offset": 0

是否可以使用 RAML 来定义它？在资源类型中？怎么样？

【参考方案1】：

这取决于您用于指定 API 实体的内容：

JSON Schema Draft 3 - 使用这些公共字段创建一个基本架构，并在每个具体架构中使用extends 机制， JSON Schema Draft 4 - 使用这些公共字段创建一个共享架构，并使用 allOf 机制将其混合到每个具体架构中， RAML 1.0 Types - 创建一个通用类型并通过type 属性在每个具体类型中引用它。

【讨论】：

好像有错别字，也许这里的第二个项目符号是指草案 4？

【参考方案2】：

使用 RAML 1，您可以使用类型和继承来定义信封和数据类型。以及适用于所有集合类型资源的资源类型，例如：

types:
    person:
        type: object
        properties:
            name:
            age:
    car:
        type: object
        properties:
           model:
           brand:
    envelop:
        type: object
        properties:
            data: person[] | car[]
            self: string
            total: integer
            limit: integer
            offset: integer
resourceTypes:
    - collection:
        get:
            responses:
                200:
                    body:
                        type: envelope
/users:
    type: collection
    get:

更多信息here、here 和 here

【讨论】：

参考链接已损坏