$ref in response example

[paulprogrammer]

I would like to use $ref in the response example in order to break up my specification into more readily manageable chunks. Examples also benefit from being externalized because they can be easily revisioned, and included verbatim in reference implementations.

desired structure:

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

Today, the children of examples are included directly, meaning the example itself using this example is:

{
  "$ref": "ProfileExample.yaml#/ProfileSearchResponseExample"
}

[paulprogrammer]

This issue arose from a discussion on swagger-ui:

swagger-api/swagger-ui#1882

[crankydillo]

Hi,

Does this same issue exist for the example field within the schema object? If so, will that be addressed as well?

Basically, we'd like the option to $ref in examples everywhere an example can be specified.

Thanks!

[jharmn]

The revised guidelines for external file usage should help clarify this once merged: #535

[fehguy]

Parent issue #560

[paulprogrammer]

We resolved this during build process by using the json-refs tool to resolve references before delivery of the final artifacts.

[webron]

You can do that now! 😱