Swagger/OpenAPI - use $ref to pass a reusable defined parameter

Question

Let's say I've got a parameter like limit. This one gets used all over the place and it's a pain to have to change it everywhere if I need to update it:

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

Can I use $ref to define this elsewhere and make it reusable? I came across this ticket which suggests that someone wants to change or improve feature, but I can't tell if it already exists today or not?

Derek

Answer 1

This feature already exists in Swagger 2.0. The linked ticket talks about some specific mechanics of it which doesn't affect the functionality of this feature.

At the top level object (referred to as the Swagger Object), there's a parameters property where you can define reusable parameters. You can give the parameter any name, and refer to it from paths/specific operations. The top level parameters are just definitions and are not applied to all operations in the spec automatically.

You can find an example for it here - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/reusableParameters.json - even with a limit parameter.

In your case, you'd want to do this:

# 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

Oglesby

Can you do this with path parameters too? Or only query parameters? – Derek

Any parameter type, wherever parameters are used (at the path level or the operation itself). The top-level parameter definition uses the same Parameter Object as the ones explicitly defined for operations. – Oglesby

Is it possible to extend a parameter? For example, the same parameter definition could be in: path in one case and in: query in another. Also could be optional in one case and required in another. – Originate

You'd have to create two separate definitions for it. – Oglesby

Can you please commt the swagger tag? See here: stackoverflow.com/documentation/swagger/commit – Tatia

Is it possible to make whole request arguments reusable? ie.: parameters: $ref: "#/parameters/requestParams" – Atavistic

@KonradGałęzowski - unfortunately, there's no support for parameter grouping. – Oglesby

Can you do this with a parameter defined in another file? - $ref: "common.yml#/parameters/limitParam"? I think you should be able to, but it breaks the codegen... – Suburb

@Suburb technically, yes. If there's an issue with the codegen, please file a ticket at the project's repo. – Oglesby

Answer 2

For completeness, here's how it would look like in 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

Variola

With these reusable components, are variables an option? Say I have a reusable parameter for Name but that name changes with the resource or API endpoint, an identifier here would be the tag, so effectively asking if I can insert the tag name in the description of a reusable parameter? – Hereon