RAML：嵌套模式

Posted 2023-02-19

【中文标题】RAML：嵌套模式

【英文标题】：RAML: Nested Schemas

【发布时间】：2015-01-19 06:07:21

【问题描述】：

1) 在编写 RAML 时，我可以在架构定义中使用嵌套吗？

例如：

schemas:
  - DNSResponse: |
      
        "type": "object",
        "properties": 
            "AnswerSection": 
                "type": "array",
                "items": (((I want a re-useable schema here. ex: ARecord)))
            ,
            "AA": "type": "boolean",
            "AD": "type": "boolean",
            ...
        
      
  - ARecord: |
      
        "type": "object",
        "properties": 
            "address": "string",
            "ttl": "number",
            "name": "string"
        
      

2) 我可以围绕一组可嵌套模式使用选择/枚举吗？

"items": [ARecord, MXRecord, PTRRecord, ...]

【参考方案1】：

1) 是的，你可以。见this example。那将是：

"items":  "$ref": "ARecord" 

2) 我相信这在 JSON Schema 草案 4 中是可能的，使用 oneOf 指令。我不认为 RAML 支持这一点。或者，您可以创建一个基本模式并让 ARecord、MXRecord 和 PTRRecord 扩展此基本模式，然后允许基本模式的项目。这在语义上不会很丰富，但可以帮助您入门。

【讨论】：

1) $ref 似乎没有被 API Designer 或 raml2html 解析，因此永远不会显示嵌套项的架构。 2）你碰巧有一个扩展模式的链接吗？除了"$schema": "http://json-schema.org/draft-03/schema"

，我在 raml 规范中没有看到任何示例

1) :"( 将问题报告给不同的项目... 2) github.com/joelittlejohn/jsonschema2pojo/wiki/Reference#extends

【参考方案2】：

由于您的问题不是 100% 需要 JSON，因此我将在答案中添加此内容...

随着 RAML 1.0 规范的发布，您可以使用 types，它可以让您做到这一点（我认为更简洁）。

这里是参考链接：http://docs.raml.org/specs/1.0/#raml-10-spec-types

RAML 1.0 引入了数据类型的概念，它提供了一种简洁而强大的方式来描述 API 中的数据。数据可以是 URI 参数（基础或资源 URI）、查询参数、请求或响应标头，当然也可以是请求或响应正文。一些类型是内置的，而自定义类型可以通过扩展（继承）内置类型来定义。在 API 需要数据的任何地方，都可以使用内置类型来描述数据，或者可以内联扩展类型来描述该数据。 CustomSecurityScheme 类型也可以像任何内置类型一样被命名和使用。

对于那些想要更少文本和更多示例的人（取自 RAML 文档）：

#%RAML 1.0 
title: API with Types
types:
  User:
    type: object
    properties:
      firstname: string
      lastname:  string
      age:       number
/users/id:
  get:
    responses:
      200:
        body:
          application/json:
            type: User

【讨论】：

如果您的用户有一个嵌套对象，例如地址：街道、邮政编码、城市、国家/地区，该怎么办？你如何嵌套那个对象？

@OmekaPhive 同样的方式。你可以嵌套types。 User 属性可以是 address，这是一种具有许多其他属性的类型。非常适合一种面向对象的方法。

【参考方案3】：

我认为以下示例适用于此。它演示了定义两种类型 Url 和 File（使用 RAML 1.0），然后使用逻辑 OR 允许 Item 中的任一类型（又名模式）作为子模式。如果需要，您可能会包含更多类型。

我还定义了一些内联示例来演示如果您使用 raml-parser 时它是如何工作的。

#%RAML 1.0
types:
    Url:
        properties:
            url:
                type: string
                example: http://www.cats.com/kittens.jpg
                description: |
                    The url to ingest.

    File:
        properties:
            filename:
                type: string
                example: kittens.jpg
                description: |
                    Name of the file that will be uploaded.


    Item:
        description: |
            An example of a allowing multiple types using RAML 1.0
        properties:
            ext:
                type: File | Url
        examples:
            file_example:
                content:
                    ext:
                        filename: video.mp4
            url_example:
                content:
                    ext:
                        url: http://heres.a.url.com/asset.jpg
            should_fail:
                content:
                    ext:
                        unexpected: blah