Example component shows "value" when referenced from a schema

[CameronGo]

Q&A (please complete the following information)

• OS: Windows 10
• Browser: Chrome
• Version: 77
• Method of installation: dist assets
• Swagger-Editor version: 3.6.37
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Swagger/OpenAPI definition:

openapi: 3.0.0
info:
  title: Example API
  version: "1"
paths:
  /communications:
    get:
      tags:
      - communications
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Communication'
components:
  schemas:
    Telephone:
      description: >-
        A 10 digit US telephone number with no punctuation      
      type: string
      minLength: 10
      maxLength: 10
      example: '7707707777'
    EmailAddress:
      type: object
      required:
      - address
      properties:
        address:
          type: string
          format: email
          example: [email protected]
    Communication:
      description: ''
      type: object
      required:
      - id
      - name
      - type
      - send_from
      properties:
        id:
          type: integer
          example: 10
        name:
          type: string
          minLength: 1
          maxLength: 45
          example: 'Notification Email'
        type:
          type: string
          minLength: 1
          maxLength: 45
          enum:
          - email
          - sms
        opt-in-only:
          type: boolean
          default: true
        send_from:
          $ref: '#/components/schemas/ContactPoint'

    ContactPoint:
      properties:
        id:
          type: integer
          example: 34
        type:
          type: string
          enum:
          - email
          - telephone
      oneOf:
      - type: object
        properties:
          email:
            $ref: '#/components/schemas/EmailAddress'
      - type: object
        properties:
          telephone:
            $ref: '#/components/schemas/Telephone'
      example:
        $ref: '#/components/examples/ContactPointEmail'

  examples:
    ContactPointEmail:
      value:
        id: 34
        type: email
        email:
          address: [email protected]

Screenshots

How can we help?

I'm not certain if this is a bug or working as expected. I'm trying to determine the most efficient way of describing examples for a ContactPoint that could be of type email or telephone. If I reference an example from the components within a schema then the value object from the example is also depicted in the rendered response body. I've tried removing the value object from the example component, but this is interpreted as invalid. If I reference the example from the components within the response body directly, the rendered example correctly depicts the intended structure of the example.

[webron]

It's a bug, but may not be the one you're thinking. example cannot use references, whereas examples can.

[CameronGo]

It's a bug, but may not be the one you're thinking. example cannot use references, whereas examples can.

Interesting, is that an OAS3 constraint or a swagger editor/UI one? If that is indeed the case, the net effect of that is to be unable to use examples in an extensible way. (Since examples support references, but are not supported in schema components, yet example is supported in schema components, but does not support references.)

Also, I'm confused, is it that example should not use references when used in a schema, or it should not use references at all?

[CameronGo]

After more testing I also see that I'm seeing the same behavior when attempting to nest examples by referencing one example from another. In this case the pictured examples are both under #/components/examples and are referenced in the responseBody, not from the schema. This behavior for certain seems incorrect since AFAIK you are intended to be able to reference one example from another and you should not see the "value" property coming in to the rendering.

[webron]

@CameronGo it's a bit difficult to follow just with the screenshot? Can you share the full definition please? If you prefer it not to be public, you can email me (email in profile).

[dmarra]

I am suffering from the same problem. the editor is not complaining about the schema, but its showing "value", "summary", etc as if it was a part of the schema.

This is incredibly odd, as it pretty much neuters the ability to use examples as components. For any non-trivial response we really have no other choice but to hard code example strings.

Is this on the radar for repairing?