Creating reusable array definitions in swagger

Question

I'm working on a definition/documentation-first specification of an API using Swagger 2.0. I've managed to break-out most reusable components into a definitions section however I am having trouble figuring out how to create reusable definitions for arrays of constants.

For example, I have a few paths that will return images, like this one:

paths:
  /resource/{imageId}:
    get:
      produces:
        - image/jpeg
        - image/png
        - image/gif
      parameters: 
        - in: path
          name: imageId
          type: string
          required: true
      responses: 
        200:
          description: Success
          schema:
            type: file

Which works just fine, but I would like to be able to define a reusable array of the values for the "produces" element so that I can reuse the same list for any path that will produce an image.

The following seemed like the intuitive approach, but swagger reports that the definition for imageMimeTypes is not valid:

paths:
  /resource/{imageId}:
    get:
      produces:
        $ref: "#/definitions/imageMimeTypes"
      parameters: 
        - in: path
          name: imageId
          type: string
          required: true
      responses: 
        200:
          description: Success
          schema:
            type: file
definitions:
  imageMimeTypes:
    - image/jpeg
    - image/png
    - image/gif

Is it possible to create a definition for an array like this? If so, what syntax should be used?

Helen · Accepted Answer · 2017-04-11 21:37:38Z

3

First of all, if these produces values are used in most operations, you can define them as global produces and override where needed.

produces:
  - image/jpeg
  - image/png
  - image/gif

paths:
  /resource/{imageId}:
    get:
      # Inherits global "produces"
      ...
  /something:
    get:
      # Overrides global "produces"
      produces:
        - application/json
      ...

Your second example is not valid, because produces cannot have a $ref value. But you can use YAML anchors to achieve a similar effect. Note that an anchor must be defined before it is used, so you need to put the list above the path definition.

x-types:
  imageMimeTypes: &IMAGE-MIME-TYPES
    - image/jpeg
    - image/png
    - image/gif

paths:
  /resource/{imageId}:
    get:
      produces: *IMAGE-MIME-TYPES
      parameters: 
        - in: path
          name: imageId
          type: string
          required: true
      responses: 
        200:
          description: Success
          schema:
            type: file

I put the list under an extension key x-types instead of definitions 1) because definitions is intended for input and output models and not random lists, and 2) to prevent the "unused definition" warning in the Swagger Editor.

This works in (at least) Swagger Editor and Swagger UI.

answered Apr 11, 2017 at 21:37

Helen

99.8k18 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

B Sharp Over a year ago

Thank you for your answer Helen. It looks like using YAML anchors will work well for our purposes. Regarding specifying a global produces definition, I should have mentioned that I'm already specifying application/json as my global value for produces since that is what most of my API will be producing, but I will have a few paths, like this one, that will return images.

B Sharp Over a year ago

Also, thank you for pointing out that these should be defined in x-types rather than definitions.

Collectives™ on Stack Overflow

Creating reusable array definitions in swagger

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related