如何在 swagger-spec 中表达“任意 JSON”？答案

【问题标题】：How to express "arbitrary JSON" in swagger-spec?如何在 swagger-spec 中表达“任意 JSON”？
【发布时间】：2014-08-13 22:04:08
【问题描述】：

假设我有一个 REST 服务，它可以接受请求正文中的任意 JSON。如何使用 swagger-spec 对其进行建模？

我考虑过Model Objects，但我只能考虑将任意 JSON（作为字符串）包装在容器 JSON 对象中，例如 {"payload": "{ some JSON object serialized to a string }"}，这并没有真正的用处。

或者，是否有其他方式表示端点可以在请求正文中接收任意 JSON？

【问题讨论】：

标签： json rest swagger

【解决方案1】：

Swagger 尝试在 API 方面具有确定性，因此不直接支持您的要求。

我能想到的实现您想要的唯一方法是将“consumes”属性设置为“application/json”并添加一个字符串类型的“body”参数。这在理论上说应该只发送 JSON，但实际上，可以发送 any 字符串。

此外，如果某些第三方工具在将其发送到服务器之前尝试将其转换为 JSON 对象，这可能会破坏它们。

【讨论】：

说得通，虽然很可惜。

【解决方案2】：

将请求的正文负载建模为parameters，架构仅为"type": "object"。然后，swagger UI 编辑器将提示用户使用包含 {} 的大文本区域，用户可以使用 JSON 对象填充该文本区域。

"/endpoint": {
      "post": {
        "parameters": [
          {
            "description": "Arbitrary JSON object payload",
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "type": "object"
            }
          }
        ]
      }

【讨论】：