Examples referenced with $ref are not rendered correctly #4924

alexgmin · 2018-10-05T11:08:40Z

Not sure if a regression of #4021

This renders the example but also adds the $$ref key

openapi: '3.0.0'
info:
  title: 'test'
  version: '1.0.0'
paths:
  /hello:
    get:
      description: 'Get welcome message.'
      responses:
        '200':
          description: 'welcome message'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Welcome'
              example:
                $ref: '#/components/examples/WelcomeExample'
components:
  schemas:
    Welcome:
      type: object
      properties:
        message:
          type: string
  examples:
    WelcomeExample:
      value:
        api_identifier: act_12345

And this one shows the $ref key instead of parsing it (Although the editor shows an error if the $ref doesn't exist):

openapi: '3.0.0'
info:
  title: 'test'
  version: '1.0.0'
paths:
  /hello:
    get:
      description: 'Get welcome message.'
      responses:
        '200':
          description: 'welcome message'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Welcome'
              example:
                $ref: '#/components/examples/WelcomeExample'
components:
  schemas:
    Welcome:
      type: object
      properties:
        message:
          type: string
  examples:
    WelcomeExample:
      value:
        api_identifier: act_12345

All of this tested in the swagger editor.

The text was updated successfully, but these errors were encountered:

lrtherond · 2018-10-05T23:31:57Z

Yep, I see that too in 3.19.2 and quite a few releases before that

sasha-borodin · 2018-10-07T23:12:37Z

In #4021, @webron states that

The spec does not support references for example fields, only examples. This means that any value of example will be rendered as-is

I'm wondering if this same spec interpretation extends to $ref usage inside example content. If I define a schema that envelops properties of other schema types, $ref usage is permitted. But If I then want to express an example, can I use the same $ref approach, or must the example be completely literal (without any $refs)? For example, is this valid according to swagger-ui team's spec interpretation, @webron :

paths:
  /order:
    post:
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/User'
                product:
                  $ref: '#/components/schemas/Product'
                quantity:
                  type: integer
            example:
              user:
                $ref: '#/components/examples/User'
              product:
                $ref: '#/components/examples/Product'
              quantity: 1
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
  examples:
    User:
      id: 1
      name: Sasha
    Product:
      id: 1
      name: Book

lrtherond · 2018-10-08T15:19:04Z

I think $ref should work in that case too. Clearly, passing a 10-KB piece of JSON example as a string is very problematic.

webron · 2018-10-10T01:34:09Z

@sasha-borodin the spec isn't explicit about it, but I would expect what you shared to be rendered simply as:

              user:
                $ref: '#/components/examples/User'
              product:
                $ref: '#/components/examples/Product'
              quantity: 1

(that is, $ref's are not being dereferenced)

sasha-borodin · 2018-10-10T01:57:56Z

@webron, thanks for the response! I think there are two issues:

The implementation both a) resolves the $ref, and b) renders an erroneous artifact of $$ref. I think that consistency needs to be achieved. Either $refs are not supported (and displayed literally), or they are supported (in which case, rendering $$ref is a bug that needs to be fixed).
Since the spec isn't explicit about the matter of resolving $refs inside examples, I would like to make a case for resolution instead of literal rendering. I think this behavior is intuitively expected by a number of users as well as some on the swagger-ui team (see @shockey's comment in Reusing examples Rendering issue. #4931). What's the most appropriate channel through which to make such a case or feature request?

Thank you again.

alexgmin · 2018-10-10T09:39:38Z

I would like add another argument to the case for resolution.
Is the current behavior for schemas.
As a developer trying to define an API, I don't see why I can have nested schema references but not nested example references.

From my point of view, what is wrong in this example is the value key being rendered. Why can I reuse schemas but not examples?

openapi: '3.0.0'
info:
  title: 'test'
  version: '1.0.0'
paths:
  /hello:
    get:
      description: 'Get welcome message.'
      responses:
        '200':
          description: 'welcome message'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Welcome'
components:
  schemas:
    Welcome:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
    Message:
      type: object
      properties:
        title:
          type: string
        info:
          type: string
      example:
        $ref: '#/components/examples/WelcomeExample'
  examples:
    WelcomeExample:
      $ref: '#/components/examples/MessageExample'
    MessageExample:
      value:
        foo: 2
        bar: 3

dkrantsberg · 2019-01-03T20:19:09Z

Encountering the same issue. Is anyone working on it?

qbedard · 2019-02-21T23:04:09Z

Been running into this lately as well. Any news?

shockey · 2019-04-05T20:11:40Z

I'm picking this up - as mentioned in #4931 (comment), we shouldn't be resolving example values at all.

OnkelTem · 2020-03-24T03:29:51Z

Just trying to clarify things.

So basically we cannot use examples not only in a good way, but in fact. Because no one in their clear mind would insert a huge block of example data right in the middle of definitions - and that is exactly what we're forced to do, because:

Arrays is what desperately needs loads of data,
but arrays can only consume example and not examples,
which is actually the only option to decouple definitions and data.
And this nonsense behavior we totally owe to some API spec, sent from above.

Did I get it right?

webron · 2020-03-24T17:36:18Z

Couldn't really follow what you're saying, but regardless, this is how the spec is defined, not something within the control of this tool.

carlos-soto · 2020-06-09T00:07:02Z

I agree with @alexgmin. Could we request the ability to nest examples so we can, uhm... reuse definitions? After all, that's the whole idea of Domains, isn't it?

hkosova · 2020-06-10T07:24:38Z

@carlos-soto you can propose changes to the OpenAPI Specification here:
https://github.com/OAI/OpenAPI-Specification/issues

dmak · 2020-06-12T11:24:30Z

Would be nice in addition to support arrays in example:

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

hkosova · 2020-06-12T14:22:06Z

@dmak you can propose changes to the OpenAPI Specification syntax constructs here:
https://github.com/OAI/OpenAPI-Specification/issues

As of OAS 3.0.3, multiple examples require the use of the examples keyword:

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

BenceSzalai · 2020-11-02T00:11:22Z

What do you think about the issue where $ref used in examples (plural, which is valid, and part of the OpenAPI specification as opposed to inside example (singular)) is dereferenced properly, but also causes an artifact of $$ref being added to the dereferenced object?

So for example this:

...
examples:
  Users:
    value:
      - $ref: '#/components/examples/User1/value'
      - $ref: '#/components/examples/User2/value'
...

Renders as this (in JSON):

[
  {
    "id": 1,
    "email": "[email protected]",
    "name": "John Doe",
    "$$ref": "#/components/examples/User1/value"
  },
  {
    "id": 2,
    "email": "[email protected]",
    "name": "Jane Doe",
    "$$ref": "#/components/examples/User2/value"
  }
]

Notice the "$$ref": "#/components/examples/User*/value" as the last property. This seems to be an issue regardless what's going on with example (singular) also mentioned in #4924 (comment)

Should that be opened as a separate issue than?

hkosova · 2020-11-17T18:03:18Z

@BenceSzalai

What do you think about the issue where $ref used in examples (plural, which is valid, and part of the OpenAPI specification as opposed to inside example (singular)) is dereferenced properly, but also causes an artifact of $$ref being added to the dereferenced object?
...
examples:
  Users:
    value:
      - $ref: '#/components/examples/User1/value'
      - $ref: '#/components/examples/User2/value'
...

This is not valid usage. $ref is supported only under examples.<name>, that is:

examples:
  Users:
    $ref: '#/components/examples/User1'

The value keyword is an analog of example (singular) and requires an inline example value.

Should that be opened as a separate issue than?

#5625

BenceSzalai · 2020-11-17T18:16:45Z

Oh, makes sense! Thanks for providing clarity!

random-developer-7 · 2022-03-10T14:31:39Z

I tried combining multiple $ref elements using allOf, just for the sake of it. Even though I'm getting a Structural error in Swagger editor, the output for examples seems to be correct. For e.g.,

examples:
 myTestExample:
  $ref: '#/components/examples/testExample'
  
components:
 examples:
  testExample:
   allOf:
    - $ref: '#/components/examples/data1'
    - $ref: '#/components/examples/data2'
  data1:
   value:
    'key1': 'value1'
  data2:
   value:
    'key2': 'value2'

This produces the output value for myTestExample as follows:

{
 'key1': 'value1',
 'key2': 'value2'
}

Is this an expected behaviour?

bodo79 · 2022-03-29T12:01:29Z

Hi @alexgmin,
I'v tried many solutions, the only one that seems to work is using 'examples' key and not 'example',
then put a single example (you should name it) and put the $ref under it.

just like this:

paths:
  /hello:
    get:
      description: 'Get welcome message.'
      responses:
        '200':
          description: 'welcome message'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Welcome'
              examples:
                WelcomeExample1: # you can give as an example name any name you want
                  $ref: '#/components/examples/WelcomeExample'

Shannanigans · 2022-05-05T14:02:54Z

@BenceSzalai
What do you think about the issue where $ref used in examples (plural, which is valid, and part of the OpenAPI specification as opposed to inside example (singular)) is dereferenced properly, but also causes an artifact of $$ref being added to the dereferenced object?
...
examples:
  Users:
    value:
      - $ref: '#/components/examples/User1/value'
      - $ref: '#/components/examples/User2/value'
...
This is not valid usage. $ref is supported only under examples.<name>, that is:
examples:
  Users:
    $ref: '#/components/examples/User1'
The value keyword is an analog of example (singular) and requires an inline example value.

Should that be opened as a separate issue than?

#5625

I am surprised to find that this ticket is closed. Using references in component examples in a similar manner to schema seems to be an intuitive and expected behaviour for many.

A list endpoint which is making use of an enveloped response becomes difficult to create an example for without duplication of the single instance example data which is required for other endpoints.

  examples:
    someResponse:
      value:
        count: 15
        next: null
        previous: null
        results:
          - $ref: '#/components/examples/exampleOne/value'
          - $ref: '#/components/examples/exampleTwo/value'

alexgmin changed the title ~~examples referenced with $ref are not rendered correctly~~ Examples referenced with $ref are not rendered correctly Oct 5, 2018

hkosova mentioned this issue Oct 9, 2018

Reusing examples Rendering issue. #4931

Closed

alexgmin mentioned this issue Mar 13, 2019

ReDoc fails to expand JSON Schema refs in examples Redocly/redoc#840

Closed

shockey added P1 type: bug labels Apr 5, 2019

shockey mentioned this issue Aug 9, 2019

fix: non-standard resolution behavior swagger-api/swagger-js#1465

Merged

shockey closed this as completed in swagger-api/swagger-js#1465 Aug 9, 2019

dmak mentioned this issue Jun 16, 2020

$ref for array example? OAI/OpenAPI-Specification#1967

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Examples referenced with $ref are not rendered correctly #4924

Examples referenced with $ref are not rendered correctly #4924

alexgmin commented Oct 5, 2018 •

edited

Loading

lrtherond commented Oct 5, 2018

sasha-borodin commented Oct 7, 2018 •

edited

Loading

lrtherond commented Oct 8, 2018

webron commented Oct 10, 2018

sasha-borodin commented Oct 10, 2018 •

edited

Loading

alexgmin commented Oct 10, 2018

dkrantsberg commented Jan 3, 2019

qbedard commented Feb 21, 2019

shockey commented Apr 5, 2019

OnkelTem commented Mar 24, 2020

webron commented Mar 24, 2020

carlos-soto commented Jun 9, 2020

hkosova commented Jun 10, 2020

dmak commented Jun 12, 2020

hkosova commented Jun 12, 2020

BenceSzalai commented Nov 2, 2020 •

edited

Loading

hkosova commented Nov 17, 2020

BenceSzalai commented Nov 17, 2020

random-developer-7 commented Mar 10, 2022

bodo79 commented Mar 29, 2022 •

edited

Loading

Shannanigans commented May 5, 2022 •

edited

Loading

Examples referenced with $ref are not rendered correctly #4924

Examples referenced with $ref are not rendered correctly #4924

Comments

alexgmin commented Oct 5, 2018 • edited Loading

lrtherond commented Oct 5, 2018

sasha-borodin commented Oct 7, 2018 • edited Loading

lrtherond commented Oct 8, 2018

webron commented Oct 10, 2018

sasha-borodin commented Oct 10, 2018 • edited Loading

alexgmin commented Oct 10, 2018

dkrantsberg commented Jan 3, 2019

qbedard commented Feb 21, 2019

shockey commented Apr 5, 2019

OnkelTem commented Mar 24, 2020

webron commented Mar 24, 2020

carlos-soto commented Jun 9, 2020

hkosova commented Jun 10, 2020

dmak commented Jun 12, 2020

hkosova commented Jun 12, 2020

BenceSzalai commented Nov 2, 2020 • edited Loading

hkosova commented Nov 17, 2020

BenceSzalai commented Nov 17, 2020

random-developer-7 commented Mar 10, 2022

bodo79 commented Mar 29, 2022 • edited Loading

Shannanigans commented May 5, 2022 • edited Loading

alexgmin commented Oct 5, 2018 •

edited

Loading

sasha-borodin commented Oct 7, 2018 •

edited

Loading

sasha-borodin commented Oct 10, 2018 •

edited

Loading

BenceSzalai commented Nov 2, 2020 •

edited

Loading

bodo79 commented Mar 29, 2022 •

edited

Loading

Shannanigans commented May 5, 2022 •

edited

Loading