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

Posted 2023-02-19

【中文标题】RAML：如何要求参数 A 或参数 B

【英文标题】：RAML : How to require parameter A OR parameter B

【发布时间】：2016-08-28 15:53:43

【问题描述】：

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

我的问题： - 我有一个用于搜索的 GET 请求，它可以采用参数 “id” 或（独占或）“reference”。 只有其中一个是必需的。

我知道怎么说“这个参数是必需的”，但我不知道怎么说“需要这些参数之一”。有没有可能？

【参考方案1】：

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

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

我使用了 union 属性。参见 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 类型定义。

【参考方案2】：

以下用 RAML 1.0 编写的示例在 Url 和 File 中定义了两个对象类型，然后在 ext 中创建另一个需要 Url 或 File 的对象 Item。如果您更改包含的示例（当前验证），您将看到如果属性不符合一个或另一个定义，它们将失败。希望有帮助！ 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

【讨论】：

感谢您的回答。我不熟悉 RAML 1.0 中的类型（直到现在我都使用 RAML 0.8）。我会阅读它以确保我能很好地解释你的例子。

不客气，基本上 schema 字段已被弃用，type 是替换它的字段。请参阅文档here。

如果您使用的是 Mulesoft Design Center，为避免出现"maxProperties facet can only be used with object types" 错误，请在尝试添加maxProperties: 1 之前输入type: File | Url。

【参考方案3】：

在 RAML 0.8 中，您不能只用一个参数来描述 queryParameters。

在 RAML 1.0 中，您可以做到这一点。您应该在 jsonschema 中使用 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

架构/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
/usersmediaTypeExtension:
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify text/xml