Вопрос: RAML: вложенные схемы


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, ...]

5


источник


Ответы:


1) Да, вы можете. Видеть этот пример , Это было бы:

"items": { "$ref": "ARecord" }

2) Я считаю, что это возможно в проекте 4 схемы JSON, используя один из  директивы. Я не думаю, что это поддерживается RAML. Кроме того, вы можете создать базовую схему и ARecord, MXRecord и PTRRecord расширить эту базовую схему, а затем разрешить элементы базовой схемы. Это не будет очень семантически богатым, но вы можете начать.


6



Поскольку ваш вопрос не на 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

2



Я думаю, что здесь приведен пример. Он демонстрирует определение двух типов Url а также File (используя RAML 1.0), а затем используя логический ИЛИ, чтобы разрешить любой тип (aka schema) в 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

2