如何在RAML中建模十进制类型

Question

我正在使用RAML建模REST API。端点（JSON格式）的响应主体是金融交易列表。每笔交易都包含一笔金额：货币和数值。以下是我的RAML file的片段，请注意amount类型的属性Transaction：

  # %RAML 1.0
  title: Trading details API
  version: v1
  mediaType: application/json
  baseUri: http://my.host.io/api/trading/v1/
  types:
    Transactions:
      type: Transaction[]
      minItems: 1
    Transaction:
      type: object
      properties:
        refNum:
          type: string 
        amount:
          type: ????
        currency:
          type: string
          minLength: 2
          maxLength: 3

  /trades
    get:
      description: Get details for a given trade
      queryParameters:
        userId:
          type: integer
          required: true

      responses:
        200:
          body:
            application/json:
              type: Transactions

不幸的是RAML没有内置的decimal类型，其他数字类型（整数，浮点数或双精度）不适合这个范围，主要是因为我需要指定.之后的位数。

所以问题是：在RAML中如何正确建模类型amount？

我需要为每个响应主体值提供一个确切的类型定义，因为这个文件将是后端和前端之间的契约（由2个不同的团队开发）。

欢迎任何帮助。

请注意，我对SO做了一些研究，最接近我的问题是：How to define money amounts in an API 。但它与RAML建模无关，答案对我没有帮助。

Answer 1

RAML在JSON Schema中有一个similar construct。你需要将type: number与multipleOf结合使用来描述小数精度。

#%RAML 1.0 DataType

type: number
multipleOf: 0.01

Answer 2

几个月后，我回来分享我的经验。

我解决它的方式是使用类型string和模式。我知道将数据类型从number更改为string的许多问题，但这种方法优雅，健壮，灵活，并且仍然易于测试和理解。

API使用者被迫以正确的方式格式化数量，并且进出API的消息是一致的，使用multiplyOf 0.0001（其中25和25.0000都被接受）无法保证一致性。

我重复使用这个解决方案并取得了很好的效果。因此，我与社区分享这一点。

解：

   [...]
   amount:
     type: string
     pattern: "^(([1-9][0-9]*)|[0])[.]([0-9]{4})$"
     currency:
       type: string
          ...

该模式接受小数部分的4 digits，强制使用.，金额不能以0开头，但0.xxxx数字族除外。

以下是接受号码的示例列表：

1.0000
54.0000
23456.1234
1.9800
0.0000
0.0001

相反，以下是被拒绝的示例列表：

0123.3453
12.12
1.1
000
01.0000
1.0
1.00
4.000

此外，您可以指定左侧的最大位数（在此示例中为10）：

pattern: "^(([1-9][0-9]{0,9})|[0])[.]([0-9]{4})$"

接受的数字示例：

1234567890.1234
3.5555
0.1234

被拒绝的数字示例：

12345678901.1234
123456789012.1234