Question

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

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

我知道如何说“这个参数是必需的”，但我不知道怎么说“需要其中一个参数”。它甚至可能吗？

Answer 1

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

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

[更新：好的，我认为这样做的方式很温和。在应该具有属性的对象中使用should_fail，请参阅下面的更新代码，该代码在验证期间未通过最终示例。]

maxProperties: 1

Answer 2

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

两者都有不同的字段，我从字段名称中检测到请求类型。即如果请求有[文件和参数]，则为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类型定义。

Answer 3

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

在RAML 1.0中，您可以这样做。您应该在jsonschema中使用oneOf来描述Type。您的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
/users{mediaTypeExtension}:
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify text/xml

RAML：如何要求参数A OR参数B.

3 个答案: