$ref for array example?

I’m trying to use $ref to single-source example values for different response properties that have similar values.

For example, from my OpenAPI 3.0.2 definition:

fileName1:
  type: string
  example:
    $ref: '#/components/examples/fileName/value'
  description: Name of file 1.
fileName2:
  type: string
  description: Name of file 2.
  example:
    $ref: '#/components/examples/fileName/value'

and the corresponding component:

  examples:
    fileName:
      value: "example-file-name.txt"

This works. Swagger Editor shows the example response as:

"fileName1": "example-file-name.txt",
"fileName2": "example-file-name.txt",

All good. Although, it took me several attempts to figure out the correct combination of nested YAML object names and $ref path; some “examples of example components” in the OpenAPI spec would help here.

But I can’t get something similar to work for arrays.

The following definition:

fileList:
  type: array
  description: List of file names.
  example:
    $ref: '#/components/examples/fileNameArray/value'
  items:
    type: string

with this component:

components:
  examples:
    fileNameArray:
      value: [filename1.txt, filename2.txt]

causes Swagger Editor to display the following example response:

"fileList": {
  "0": "filename1.txt",
  "1": "filename2.txt"
}

which is not what I want; not an array.

To get the desired example response for an array, it seems I can’t use $ref; I have to code the example inline in the definition:

fileList:
  type: array
  description: List of file names.
  example: [filename1.txt, filename2.txt]
  items:
    type: string

Am I missing something? Am I doing something wrong? Is there an elegant way to use $ref to supply an example value for an array?

Finally, in case you’re wondering, this:

fileList:
  type: array
  description: List of file names.
  items:
    type: string
    example:
      $ref: '#/components/examples/fileName/value'

gives this example response:

"fileList": [
  {
    "$ref": "#/components/examples/fileName/value"
  }
]

(yes, the literal “$ref” and its path)

[dmak]

OpenAPI only supports references in examples. It does not support references in example.

Is there any way to improve / extend the specification related to that? It would be nice to support references in example and in addition to that, support arrays in some way, like this:

responses:
  "200":
    content:
      application/json:
        example:
          - $ref: "#/components/examples/sample1"
          - $ref: "#/components/examples/sample2"
          - $ref: "#/components/examples/sample3"

See also discussion in Swagger bugtracker.

[webron]

To clarify - the OpenAPI only supports references in examples. It does not support references in example. Anywhere that a $ref is used within example, it should be treated as the literal value of that example. So if Swagger Editor parses the reference in that case - that’s a bug. However, that’s a tooling issue indeed, and should be filed on the tool itself.