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?

score 157 · Accepted Answer · edited Sep 25 '20 at 09:41

157

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

edited Sep 25 '20 at 09:41

helvete

2,455
13
33
37

answered Nov 19 '14 at 09:24

Ron

14,160
3
52
39

1

Can you do this with path parameters too? Or only query parameters? – brandonscript Nov 19 '14 at 17:41
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. – Ron Nov 19 '14 at 17:45
8

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. – Sep 28 '15 at 20:10
9

You'd have to create two separate definitions for it. – Ron Sep 29 '15 at 00:34
Can you please commt the swagger tag? See here: http://stackoverflow.com/documentation/swagger/commit – Stephan Aug 08 '16 at 06:09
4

Is it possible to make whole request arguments reusable? ie.: parameters: $ref: "#/parameters/requestParams" – Konrad Gałęzowski Nov 15 '16 at 10:06
@KonradGałęzowski - unfortunately, there's no support for parameter grouping. – Ron Nov 15 '16 at 16:28
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... – Adam Dec 13 '17 at 21:00
@Adam technically, yes. If there's an issue with the codegen, please file a ticket at the project's repo. – Ron Jan 03 '18 at 18:58

score 48 · Answer 2 · edited Sep 25 '20 at 13:59

48

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

edited Sep 25 '20 at 13:59

helvete

2,455
13
33
37

answered Jan 21 '19 at 09:22

milan

11,872
3
42
49

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? – Mike Feb 08 '23 at 16:54

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

2 Answers2

Linked

Related