0

I followed the OAS 3.0 specification to write my document in YAML, but the result rendered by Swagger Editor is malformed.

The responses object under some operation object

  responses:
    200:
      description: "..."
      content:
        application/json:
          schema:
            $ref: '...'
          example:
            $ref: '#/components/examples/person'

The example I want to reference

components:
  examples:
    person:
      value:
        name: "Joe"
        description: "I am a programmer"

What I see in the right side of Swagger Editor (rendered result)

{
  "value": {
    "name": "Joe",
    "description": "I am a programmer"
  },
  "$$ref": "#/components/examples/person"
}

What I expected

{
    "name": "Joe",
    "description": "I am a programmer"
}

I tried to append value to the referencing statement,

$ref: '#/components/examples/person/value'

and here is what I got.

{
  "name": "Joe",
  "description": "I am a programmer",
  "$$ref": "#/components/examples/person/value"
}

I feel this is not the right way to go because appending value to each referencing statement seems pretty weird to me, and still, it does not work as expected.

I tried to google, but most results are irrelevant. I'm wondering if my syntax is wrong or it's Swagger Editor not working correctly. Any advice is appreciated, thank you.

David Chen
  • 1,777
  • 2
  • 12
  • 23
  • To recap the ^^ linked Q&A: `example` (singular) does not support `$ref` and requires an inline example. `$ref` can be used in `examples` (plural), but only to reference the whole example and not parts of the example. If you use Swagger UI - keep in mind that it currently supports `example` but not `examples`; support for `examples` is tracked in https://github.com/swagger-api/swagger-ui/issues/2651. – Helen Oct 23 '18 at 13:19
  • @Helen Thank you so much! It happens to clarify my confusion why using `examples` does not work out in my Swagger Editor. – David Chen Oct 23 '18 at 15:49

0 Answers0