如何在 RAML 中模拟小数类型

Question

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

  # %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 架构中有一个 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 数字族除外。

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

以下是 rejected 的示例列表：

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

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

已接受 个号码的示例：

1234567890.1234
3.5555
0.1234

拒绝号码的示例：

12345678901.1234
123456789012.1234

如何在 RAML 中模拟小数类型

How to model decimal type in RAML

currency

raml