Swagger/OpenAPI - 使用 $ref 传递可重用的定义参数

Question

假设我有一个参数叫做limit。这个参数在许多地方都被使用，如果我需要更新它，那么要到处修改它就很麻烦：

parameters:
    - name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: number
      format: int32

我能否使用 $ref 在其他地方定义并使其可重用？我看到了这个问题，其中建议有人想要更改或改进功能，但我无法确定它是否已经存在于今天或者不存在。

- brandonscript

Answer 1

这个功能在Swagger 2.0中已经存在。链接的票证讨论了一些具体的机制，但这不会影响此功能的功能。

在顶层对象（称为Swagger对象）中，有一个parameters属性，您可以在其中定义可重用的参数。您可以给参数任何名称，并从路径/特定操作引用它。顶层参数只是定义，不会自动应用于规范中的所有操作。

您可以在此处找到一个示例-https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json，甚至带有限制参数。

在您的情况下，您需要执行以下操作：

# define a path with parameter reference
/path:
   get:
      parameters:
         - $ref: "#/parameters/limitParam"
         - $ref: "#/parameters/offsetParam"

# define reusable parameters:
parameters:
   limitParam:
      name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: integer
      format: int32
   offsetParam:
      name: offset
      in: query
      description: Offset from which start returned results
      required: false
      type: integer
      format: int32

- Ron

---

你能用路径参数做到这一点吗？还是只能用查询参数？ - brandonscript

任何参数类型，无论参数在路径级别还是操作本身使用。顶层参数定义使用与显式定义操作的参数对象相同。 - Ron

可以扩展参数吗？比如说同一个参数定义可能在一个情况下是 in: path，在另一个情况下是 in: query。也可能在一个情况下是可选的，在另一个情况下是必需的。 - user372702

需要创建两个独立的定义来表示它。 - Ron

能否让整个请求参数可重用？例如： 参数： $ref: "#/parameters/requestParams" - Konrad Gałęzowski

Answer 2

为了完整性，这是在OpenAPI（也称为Swagger v3）中的样子：

openapi: "3.0.0"
servers:
    - url: /v1
      description: local server

paths:
   /path:
      get:
         parameters:
            - $ref: "#/components/parameters/limitParam"

components:
   parameters:
      limitParam:
         name: limit
         in: query
         description: Limits the number of returned results
         required: false
         schema:
            type: integer
            minimum: 10
            default: 10
            multipleOf: 10 # matches 10, 20, ...
            format: int32

- milan

---

有了这些可重复使用的组件，变量是一个选项吗？假设我有一个可重复使用的参数 Name，但该名称随资源或 API 端点而更改，此处的标识符将是标签，因此有效地询问是否可以在可重复使用参数的描述中插入标签名称？ - Mike