$ref for array example?

[GrahamHannington]

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)

[handrews]

Is it valid to use a $ref with example? Skimming the spec, I see examples (note plural) takes an Example Object or Reference Object, while example(singluar) takes Any which might just mean any literal object but not a reference?

As for the reference sort-of working but showing up as an object, that seems like a tooling issue, not a spec issue, so you should open that on the Swagger Editor repo. This repo is only for issues with the specification.

[GrahamHannington]

@handrews,

Re:

Is it valid to use a $ref with example?

Good question. I had—fuzzy thinking, I'll admit—assumed so. Especially because, except for arrays, it works in Swagger Editor. Rereading the spec (prompted by your comment; thank you), I suspect the answer is "no".

The Swagger documentation topic "Adding Examples" (by SmartBear; not the OpenAPI spec) states that:

schemas and properties support singular example but not multiple examples.

That documentation is consistent with the behavior of Swagger Editor 3.6.31 (the latest), which reports an error when I attempt to specify examples for a property:

Structural error at ... should NOT have additional properties
additionalProperty: examples

Yet the OpenAPI 3.0.2 spec shows a property with examples:

properties:
  name:
    type: string
    examples:
      name:
        $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example

As you say:

This repo is only for issues with the specification.

I'm going to think some more about this, but right now, I suspect what I'll need to do is ask the Swagger Editor (and UI?) developers to support examples for properties (as shown in the OpenAPI spec), and then use $ref with examples, not example.

I'd welcome your further thoughts on this. But I understand if you consider this to be a tooling issue, and not appropriate for further comment here.

[handrews]

@GrahamHannington sorry for the lack of response, I've been focused on getting JSON Schema 2019-09 out the door.

This is definitely something you should work out with the Swagger tooling folks. My focus is primarily JSON Schema (and $ref in general since it comes from there), but once you get outside of that my knowledge of OAS is a bit shaky.

[handrews]

@webron @MikeRalphson should this be closed as a tooling issue?

[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.

[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.

[billytetrud]

This is a pretty big rough edge if you can neither reference an array item, nor reference a non-array item as part of an array.