Example reused in a property is rendering the value keyword

Q&A

• OS: Ubuntu 18.04
• Browser: Firefox
• Version: 71.0
• Method of installation: docker
• Swagger-UI version: v3.24.3
• Swagger/OpenAPI version: OpenAPI 3.0.2

Content & configuration

Swagger/OpenAPI definition:

openapi: 3.0.2
info:
  title: Test
  description: Test
  version: "0.1"
paths:
  /first:    
    get:
      description: Get
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestMeta'
  /second:    
    get:
      description: Get
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestMeta'
              examples:
                metaExample:
                  $ref: '#/components/examples/MetaContent2'
components:
  schemas:
    RequestMeta:
      description: Blabla
      type: object
      required:
        - request
      properties:
        request:
          description: 'Schema version(s) to be used for the components specified'
          type: object
          example: 
            $ref: '#/components/examples/MetaContent'
  examples:
    MetaContent:
      value:
        Individual: 
          - "ga4gh-phenopacket-individual-v0.1"
          - "ga4gh-schemablocks-individual-v0.1"
        Variant:
          - "ga4gh-variant-representation-v0.1"
          - "ga4gh-schemablocks-beacon-variant-v0.1"
    MetaContent2:
      value:
        request:
          Individual: 
            - "ga4gh-phenopacket-individual-v0.1"
            - "ga4gh-schemablocks-individual-v0.1"
          Variant:
            - "ga4gh-variant-representation-v0.1"
            - "ga4gh-schemablocks-beacon-variant-v0.1"

Screenshots

The response example rendered for the endpoint /first:

The response example rendered for the endpoint /second:

How can we help?

To define examples it is mandatory to use the keyword value:

  examples:
    MetaContent:
      value:
        Individual: 
          - "ga4gh-phenopacket-individual-v0.1"
          - "ga4gh-schemablocks-individual-v0.1"
        Variant:
          - "ga4gh-variant-representation-v0.1"
          - "ga4gh-schemablocks-beacon-variant-v0.1"

I would expect that the value keyword is not rendered because it's not part of the example but you can see in the first screenshot that it is rendered.

On the other hand, if you reference the example in the responses section, the value keyword is not rendered, as you can see in the second screenshot.

So, it seems the behaviour is different if the example is reused in a property or in a response.

Is it a bug or am I doing something wrong?

Thanks!

Start by loading the supplied OpenAPI 3.0.2 definition in Swagger UI v3.24.3 and compare the /first and /second response examples. Trace how the reused MetaContent example is rendered when referenced from a property versus a response; done means the property rendering no longer displays the value keyword while the example content remains correct.