api - RAML 默认信封

Question

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

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

是否可以使用 RAML 来定义它？在资源类型中？如何？

Answer 1

使用 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:

更多信息在这里，这里和这里

Answer 2

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

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