Swagger 2.0 中的嵌套查询参数

Question

我正在使用 Swagger 2.0 记录 Rails 应用程序，并使用 Swagger-UI 作为人类可读的文档/沙盒解决方案。

我有一个资源，客户端可以在其中存储任意元数据以供以后查询。根据 Rails 约定，查询将像这样提交：

/posts?metadata[thing1]=abc&metadata[thing2]=def

Rails 将哪些参数转换为：

{ "metadata" => { "thing1" => "abc", "thing2" => "def" } }

它可以很容易地用于为数据库生成适当的WHERE 子句。

Swagger 中是否支持类似的内容？我希望最终让 Swagger-UI 提供一些方法来修改生成的请求以添加 metadata 命名空间下的任意参数。

Answer 1

这似乎尚不支持（在您提出问题后 2 年多），但在 OpenAPI github repo 上正在进行关于添加对此的支持的讨论和公开票。他们将这种类型的嵌套称为deepObjects。

还有另一个未解决的问题，尝试实现here。然而，使用最新的稳定 swagger-ui 版本，我观察到它按预期工作：

    "parameters": [
      {
        "name": "page[number]",
        "in": "query",
        "type": "integer",
        "default": 1,
        "required": false
      },
      {
        "name": "page[size]",
        "in": "query",
        "type": "integer",
        "default": 25,
        "required": false
      }

这会显示预期的对话框，并与 Try it out 一起工作服务器。

我认为没有指定任意值或选择值（例如枚举）的好方法，因此您可能必须为每个嵌套选项添加参数。