RAML 中示例 json 的动态填充

Posted 2023-02-19

【中文标题】RAML 中示例 json 的动态填充

【英文标题】：Dynamic population of example json in RAML

【发布时间】：2015-02-08 23:57:28

【问题描述】：

我喜欢 RAML 在声明 resourceType 时如何动态引用不同的模式，例如：

resourceTypes:
  - collection:
      get:
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
      post:
        body:
          application/json:
            schema: <<schema>>Create
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>

在这里我可以像这样使用它

/users:
  type:  collection:  schema: user  

RAML 会给我来自 GET 和 POST 的 user 模式响应，并且还使用 userCreate 模式发送 POST 请求。凉爽的！现在我可以用大量不同的模式重用我的集合定义。

但现在我也想为所有内容提供示例 json，我希望以另一种方式利用 <<schema>> var 来利用“代码重用”。我希望能够做到

resourceTypes:
  - collection:
      get:
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
                example: examples/v1-<<schema>>.json
      post:
        body:
          application/json:
            schema: <<schema>>Create
            example: examples/v1-<<schema>>-create.json
        responses:
          200:
            body:
              application/json:
                schema: <<schema>>
                example: examples/v1-<<schema>>.json

但不幸的是，这不起作用。我收到一个错误提示

error: File with path "/examples/v1-%3C%3Cschema%3E%3E.json" does not exist

所以现在我不得不手动将其添加到我的所有收藏中，上面的 /users 示例已成为

/users:
  type:  collection:  schema: user  
  get:
    responses:
      200:
        body:
          application/json:
            example: !include examples/v1-user.json
  post:
    body:
      application/json:
        example: !include examples/v1-user-create.json
    responses:
      200:
        body:
          application/json:
            example: !include examples/v1-user.json

对我来说，这只是添加示例的大量开销。特别是当我想在许多资源上重复该模式时。

问题：有没有办法做到这一点？

【参考方案1】：

不，根据规范，RAML 0.8 中不允许这样做。不过在未来的版本中可能会允许这样做。

【讨论】：

RAML 1.0 也不允许这样做，在specification 中说：!include 标记参数必须是静态的：即，它不得包含任何资源类型参数或特征参数。

【参考方案2】：

由于 RAML 只是一个标准，我首先要问：谁/什么引发了这个错误？ （我的意思是，你用的是什么工具？） 另外：您确定示例（第一个）吗？它没有使用 !include，因此，甚至不应该打算访问那个不存在的文件（我假设您在原始脚本中使用了 !includes，但在此处复制时省略了该文件）。

另外，我知道您不是在要求这个，但以防万一： - 您可以传递 2 个参数（作为一种解决方法），一个用于模式，另一个用于示例（它仍然是开销，但不是硬编码）。 - 你知道保留参数吗？根据具体情况使用那个+“singularize”或“pluralize”，也可以帮助你在你的重用企业中；）看看http://raml.org/docs-200.html#parameters