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


84

假设我有一个类似的参数limit。这个地方到处都是,如果我需要更新它,那么到处都必须更改它是一个痛苦的事情:

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

我可以使用$ ref在其他地方定义它并使其可重用吗?我碰到了这张票,暗示有人想更改或改进功能,但是我不知道它是否已经存在?

Answers:


132

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

您也可以使用路径参数来执行此操作吗?还是仅查询参数?
brandonscript 2014年

任何参数类型,无论使用参数的位置(在路径级别还是在操作本身)。顶级参数定义使用与为操作明确定义的参数对象相同的参数对象。
罗恩2014年

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

8
您必须为其创建两个单独的定义。
罗恩

1
是否可以使整个请求参数可重用?即:参数:$ ref:“#/ parameters / requestParams”
KonradGałęzowski16年

28

为了完整起见,这是在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
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.