使用 Swagger 记录 OData 运算符答案

【问题标题】：Documenting OData operators using Swagger使用 Swagger 记录 OData 运算符
【发布时间】：2017-10-28 00:49:02
【问题描述】：

我们正在开发一些新的 API，并将使用 OData 来提供过滤器。我们支持多种运算符，例如 eq、ne 和 not、contains、startwith、endwith 等。对于现有的 API，我们使用 Swagger 作为文档。这些 API 具有简单的查询参数，不支持任何运算符。

对于新的 API，我想知道我们是否可以使用 Swagger 记录 OData 运算符。

使用新 API 的示例查询：

GET /users?filters=(firstName eq SAM) and (age le 35)
GET /users?filters=(firstName eq SAM) and (age le 35) or (contains(lastName, 'Tom'))

谢谢！

【问题讨论】：

标签： rest odata swagger swagger-2.0

【解决方案1】：

在参数字段下允许引用规范中的查询参数。您可以将参数类型添加为查询，并可以在描述下添加其他注释

paths:
  /users:
    get:
      summary: Gets a user by ID.
      parameters:
        - in: query
          name: firstName
          type: string
          description: first name of user

【讨论】：

是的，这是一种方法，但我将其作为最后的手段。我想知道 swagger 中是否有任何内置支持来指定支持的 filter 参数运算符，而不是在描述中指定。