$ref in response example is not correctly processed

[paulprogrammer]

I have a responses block that uses $ref to include an example:

      responses:
        200:
          description: Success
          schema:
            $ref: 'profile-models.yaml#/ProfileSearchResponse'
          examples:
            application/json:
              $ref: 'ProfileExample.yaml#/ProfileSearchResponseExample'

The $ref for the schema is correctly processed and rendered in the swagger-ui, but the $ref for the example shows the following in the swagger-ui display:

I would expect that the content of the $ref would appear as if it were inline.

[fehguy]

This use case should be covered already. Can you verify the versions that you're using? And assuming you have a file called profile-models.yaml at the same location as your swagger.json?

[webron]

Actually, I wouldn't expect this to be supported. The Example Object has a wildcard value and the results would be displayed as-is. While the spec is not explicit either way, personally that's how I'd interpret it (it is also not included in our reusability guide). Since it potentially makes sense, I'd suggest opening a ticket on the spec so the support for it would be more explicit in the next version.

[paulprogrammer]

@fehguy I downloaded from the master branch just a few days ago. The first reference (to profile-models.yaml in schema) works fine -- it's the second (to ProfileExample.yaml) in examples which does not.

@webron That kinda makes sense, but it conflicts with the definition of $ref inherited from the json-schema spec which is supposed to behave the same way everywhere.

I need to break up the spec, because it's otherwise becoming an unruly document without any way to divide the work amongst my team. Examples are a great thing to externalize, because they can then stand alone, be referenced, updated, or included verbatim in sample implementations.

[fehguy]

@webron is right. Examples are taken as literal objects or strings and regardless of rendering they will not be processed for resolution.

[webron]

@paulprogrammer - your expectations are understandable, which is why I encourage you to open a ticket on it on the spec itself.

[paulprogrammer]

I opened an issue in the specification #544 to address this.

[webron]

Already labeled ;)