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

假设我有一个类似于

limit

的参数。这一款在各地都有使用，如果我需要更新它，就必须到处更换它，这是一种痛苦：

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

---

我可以使用$ref在其他地方定义它并使其可重用吗？我发现有人想更改或改进该功能，但我不知道它现在是否已经存在？

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

在顶级对象（称为招摇过市对象）中，有一个

parameters

属性，您可以在其中定义可重用的参数。您可以为参数指定任何名称，并从路径/特定操作中引用它。顶级参数只是定义，不会自动应用于等级库中的所有操作

你可以在这里找到一个例子——即使有一个极限参数

在您的情况下，您希望执行以下操作：

#使用参数引用定义路径
/路径：
获取：
参数：
-$ref:“#/parameters/limitParam”
-$ref:“#/parameters/offsetParam”
#定义可重用参数：
参数：
limitParam：
名称：限额
in:查询
描述：限制返回结果的数量
必填项：false
类型：整数
格式：int32
偏移参数：
名称：偏移量
in:查询
描述：起始返回结果的偏移量
必填项：false
类型：整数
格式：int32

为了完整起见，以下是在（又称招摇过市v3）中的外观：

openapi：“3.0.0” 服务器： -url:/v1 描述：本地服务器 路径： /路径： 获取： 参数： -$ref:“#/components/parameters/limitParam” 组件： 参数： limitParam： 名称：限额 in:查询 描述：限制返回结果的数量 必填项：false 模式： 类型：整数 最少：10 默认值：10 倍数：10#匹配10，20。。。 格式：int32

---

您也可以使用路径参数执行此操作吗？或仅查询参数？任何参数类型，无论在何处使用参数（在路径级别或操作本身）。顶级参数定义使用与为操作显式定义的参数对象相同的参数对象。是否可以扩展参数？例如，在一种情况下，相同的参数定义可以是：path中的

，在另一种情况下可以是：query

中的

。在一种情况下可能是可选的，在另一种情况下可能是必需的。您必须为其创建两个单独的定义。是否可以使整个请求参数可重用？例如：参数：$ref:“#/parameters/requestParams”