either/or 正文属性和多个示例

Question

我是 RAML 的新手，最近继承了一个项目，我需要更新以反映新规范。

这是一个相当简单的 RAML 文档，我所做的只是添加一个新主体属性，我想展示多个示例。

之前有一个 "codeType1" 属性，这是 post 所必需的。

现在，有一个新的 "codeType2" 属性，并且需要两者之一。因此，codeType1 或 codeType2 必须位于 post 正文中。我不知道如何在 RAML 中表达该要求。

另外，我想为每个场景举两个例子。

我可以添加新的codeType，但我不知道如何表达验证规则。

这是我目前拥有的：

#%RAML 1.0
title: Auth Service
version: v1
protocols: [HTTPS]
mediaType: application/json

/auth:
    post:
      description: Authenticate a client to the API.
      body:
        application/json:
          properties:
            {
            "codeType1": {
                type: string,
                required: true
              },
            "codeType2":{
                type: string,
                required: true
              },
            "userId":{
                type: string,
                required: true
              },
            "password":{
                type: string,
                required: true
              },
            }
          example:
            {
              "codeType1":"994056",
              "codeType2":"##0023",
              "userId":"name@email.com",
              "password":"Abc123!",
            }
      responses:
        200:
          description: Successful authentication.
          body:
            application/json:
              example:
                {
                  "status": "success",
                  "message": "Authentication success",
                  "data": {
                    "token": "SDKFHDSLFDJSFDKJFDHSFLJKFHLSKFSFLKFLSDFJHSLHFSDF"
                  }
                }

Answer 1

试试这个：

#%RAML 1.0
title: Auth Service
version: v1
protocols: [HTTPS]
mediaType: application/json

types:
  UserCred:
    properties:
      userId:
      password:
  Type1:
    type: UserCred
    properties:
      codeType1:
  Type2:
    type: UserCred
    properties:
      codeType2:

/auth:
    post:
      description: Authenticate a client to the API.
      body:
        application/json:
          type: Type1 | Type2
          examples:
            ex1: 
              codeType1: "994056"
              userId: "name@email.com"
              password : "Abc123!"
            ex2:
              codeType2: "12345"
              userId: "anothername@email.com"
              password: "ZYX098"

我只复制了我修改过的部分。

以下是我在上面使用的 RAML 1.0 规范中的一些参考资料：

Union types
Here's an example that sets mutually exclusive types for queryString 适用于您尝试完成的事情。

either/or 正文属性和多个示例

either/or body properties and multiple examples

api

raml