RAML：如何要求参数 A 或参数 B

Question

我正在用 RAML 编写一些 REST 文档，但我卡住了。

我的问题： - 我有一个用于搜索的 GET 请求，它可以使用参数 "id" 或（exclusive or）"reference"。 只需要其中之一。

我知道怎么说 "this param is required" 但我不知道怎么说 "having one of these params is required"。有可能吗？

Answer 1

以下用 RAML 1.0 编写的示例在 Url 和 File 中定义了两个对象类型，然后创建另一个对象 Item，它需要 Url 或 File在 ext。如果您更改包含的示例（当前验证），如果属性不符合一个或另一个定义，您将看到它们失败。希望有帮助！ LMK 如果您还有任何其他问题，我会尽力而为。

[编辑：嗯，我想我现在看到了你的问题，我刚刚添加的最后一个例子，名为 should_fail，（在例子中每种类型都有一个）仍然有效，你想要一种方法使其无法通过验证。]

[更新：好吧，我想出了一个稍微老套的方法来做到这一点。在应该单独显示属性的对象中使用 maxProperties: 1，请参阅下面更新的代码，该代码在验证期间未能通过最终示例。]

#%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 yet requiring 
            one AND ONLY one of two possible types using RAML 1.0
        properties:
            ext: 
                maxProperties: 1
                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:
                        url: http://heres.a.url.com/asset.jpg
                        filename: video.mp4

Answer 2

在 RAML 0.8 中，您无法仅用一个参数来描述 queryParameters。

在 RAML 1.0 中你可以这样做。您应该在 json 模式中使用 oneOf 来描述类型。您的 queryParameters 应该使用这种类型。示例：

api.raml

#%RAML 1.0
title: AUTH microservice
mediaType: application/json
protocols: [HTTPS]
types:
  - example: !include schemas/example.json
/example:
  get:
    queryParameters:
      type: example

schemas/example.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "id": "file://schemas/credentials.json",
  "oneOf": [
    {
      "properties": {"key1": {"type": "string"}},
      "additionalProperties": false
    },
    {
      "properties": {"key2": {"type": "string"}},
      "additionalProperties": false
    }
  ]
}

您也可以使用 uriParameters。也许对你的情况有帮助。

#%RAML 0.8
title: API Using media type in the URL
version: v1
/users{mediaTypeExtension}:
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify text/xml

Answer 3

我遇到了同样的问题。用户可以提供文本输入或文件输入，但不能同时提供。

两者都有不同的字段，我从字段名称中检测到请求类型。即如果请求有[文件和参数]，它是一个 FileInput。如果请求有 [文本和参数]，它是一个 TextInput。不允许在同一请求中同时提供文本和文件。

我使用了联合属性。请参阅中的 CatAndDog 示例 Raml 200 documentation 举个小例子。您可以按如下方式定义类型。

types:
  FileInput:
    properties:
      parameters:
        type: Parameters
        description: (...)
      files:
        type: ArchiveCollection | FileCollection
        description: (...)


  TextInput:
    properties:
      parameters:
        type: Parameters
        description: (...)

      texts:
        type: TextCollection
        description: (...)

然后在我的 POST 请求正文中：

/your_route:
  post:
    body:
      multipart/form-data:
        type: TextInput | FileInput

正文中的字段使用 TextInput 或 FileInput 类型定义。

RAML：如何要求参数 A 或参数 B

RAML : How to require parameter A OR parameter B

api

raml