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

Posted 2023-02-16

【中文标题】Swagger/OpenAPI - 使用 $ref 传递可重用的定义参数

【英文标题】：Swagger/OpenAPI - use $ref to pass a reusable defined parameter

【发布时间】：2015-01-16 06:40:43

【问题描述】：

假设我有一个像limit 这样的参数。这个到处都在使用，如果我需要更新它，就不得不到处更改它是一件痛苦的事：

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

我可以使用 $ref 在别处定义它并使其可重用吗？我遇到了this ticket，它暗示有人想要更改或改进功能，但我不知道它今天是否已经存在？

【参考方案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

【讨论】：

你也可以用路径参数来做这个吗？还是只查询参数？

任何参数类型，无论在何处使用参数（在路径级别或操作本身）。***参数定义使用与为操作显式定义的参数对象相同的参数对象。

是否可以扩展参数？例如，相同的参数定义在一种情况下可能是in: path，而在另一种情况下可能是in: query。在一种情况下也可以是可选的，在另一种情况下是必需的。

您必须为它创建两个单独的定义。

是否可以使整个请求参数可重用？即：参数：$ref：“#/parameters/requestParams”

【参考方案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