首页 文章

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

提问于
浏览 次
68

让's say I' ve得到像 limit 这样的参数 . 这个地方到处都是用的，如果我需要更新它，就必须在任何地方进行更改：

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

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

swagger swagger-2.0 openapi

3 回答

  • 113

    此功能已存在于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"

# define reusable parameters:
parameters:
   limitParam:
      name: limit
      in: query
      description: Limits the number of returned results
      required: false
      type: integer
      format: int32
    回复于
  • 0

    为了完整性，这里是OpenAPI（a.k.a 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
    回复于
  • 1

    你能用这种方式链接一组多个参数吗？即

    paths:
  /path:
    get:
      parameters:
        - $ref: "#/components/parameters/params"
components:
  parameters:
    params:
      - name: foo
        schema:
          type: string
      - name: bar
        schema:
          type: integer

    params定义了多个参数，比如limit，offset，lastModifiedAfter ......我无法使用，只能定义一个paameter .

    回复于

相关问题