The example from json file cannot displayed correctly after upgarde Swagger-UI to 3.24.3

[wangjiong04]

Q&A (please complete the following information)

• OS: windows
• Browser: chrome
• Version: [e.g. 22]
• Method of installation: [e.g. npm, dist assets]
• Swagger-UI version: 3.24.3
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Swagger/OpenAPI definition:

# your YAML here
In our yaml file, we use a json file located the same level as the example:
RegisterConsumerAccountRequest:
        description: Consumer registration request payload.
        content:
            application/json:
                schema:
                   $ref: '#/components/schemas/RegisterConsumerAccountRequest'
                example:
                  $ref: 'create-customer-example.json'

Before upgraded, our Swagger-UI is 3.22.1, all the display are correct

After we upgraded to 3.24.3, the examples are disappeared but we didn't change any other thing

[hkosova]

The current behavior is actually correct because the example keyword does not support $ref. To reference an external example of request/response body you must use examples.<name>.externalValue:

RegisterConsumerAccountRequest:
        description: Consumer registration request payload.
        content:
            application/json:
                schema:
                   $ref: '#/components/schemas/RegisterConsumerAccountRequest'
                examples:
                  Create customer example:
                    externalValue: 'create-customer-example.json'

However, externalValue examples are currently not supported in Swagger UI; this is tracked in #5433. As a workaround you can use inline examples instead of external examples.

[wangjiong04]

Thank you!
Will the examples..externalValue support the local file reference when the issue get fixed?

[hkosova]

I think so.

[kirkoman]

@wangjiong04 Does it work if you merge the example in as the schema-level "example" instead of using the media-type-level "example"? I am using such a workaround, with the difference that I am referencing components, not files (so I'm not sure if it will work for you). E.g.,

RegisterConsumerAccountRequest:
        description: Consumer registration request payload.
        content:
            application/json:
                schema:
                     allOf:
                         - $ref: '#/components/schemas/RegisterConsumerAccountRequest'
                         - example:
                             $ref: 'create-customer-example.json'

[hkosova]

@kirkoman

- example:
    $ref: 'create-customer-example.json'

won't work because example does not support $ref.

This particular scenario - pointing to an external JSON data example - is defined using examples.<name>.externalValue, as shown in my previous comment.

[hkosova]

Closing in favor of #5433.
Please follow #5433 for updates on externalValue support.

[kirkoman]

@hkosova While I agree that example does not support $ref (nor should it according to the spec), allOf does support it. But allOf is not supported in the media object, only in the schema object. So my suggestion was to use the schema.example but to merge it with the referenced schema using allOf. I know this works (at least for component references) because I'm using it extensively to accomplish nested example references. My doubt was about whether it would work for referencing a json file (but I think it will).

It is possible this behavior is a bug, but the schema seems ambiguous. Do you think I should open a separate issue about it? OTOH since I'm actively using it, I don't really want it to be fixed. 😬

I just confirmed again with this example (3.24.3), let me know if I am missing something:

components:
  examples:
    SomeBasicType:
      value:
        is_it_some_text: Yes it is!
  schemas:
    SomeBasicType:
      type: object
      properties:
        is_it_some_text:
          type: string

/some/route:
  post:
    requestBody:
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/SomeBasicType'
              - example:
                  $ref: '#/components/examples/SomeBasicType/value'