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?

Answer 1

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.