I think a $ref under example should be left untouched during bundling

[michaelgwelch]

Per OAI/OpenAPI-Specification#666 (and the spec) you can't use a $ref under an example.

I however did do that (not realizing it wasn't correct) and "it worked". However, when I went to reference my example a second time I ended up with an example that looked like this

I could not figure out why it worked the first time and then didn't work the second time.

Well we are using multiple files for our schema and using this tool to bundle everything together. The bundler sees the $ref under example and treats it like any other $ref. The first time it sees the $ref it gets "inlined" and the other instances of $ref to the same file get updated $ref links.

I think the bundler should leave any $ref under an example alone. (unless the tool is attempting to make $ref under an example just "work", in which case more work would be needed at the example sites.)

Note: I wasn't using components, but even when I did update my files to use components correctly, it just makes the problem slightly worse. In this case the reference file gets inlined into components as you'd expect and then every other referencing site ends up with something like the screenshot above.

[michaelgwelch]

Here's just a real minimal example of the issue.

openapi: 3.0.3
info:
  title: Pets
  description: Pet store
  version: '0.3'

components:
  examples: 
    speed:
      summary: Speed of Pet
      value: Fast

paths:

  /pets:
    get:
      responses:
        '200':
          description: 
          content:
            application/json:
              example:
                $ref: '#/components/examples/speed'
              schema:
                type: string
  

And here's the rendered output:

[michaelgwelch]

I wrote up this issue because I was completely unaware that I was using example incorrectly because if you follow my incorrect set of steps

1. Create a shared example and store it in a file
2. In a part of a spec reference the example using

   example:
     $ref: /link/to/file

3. run bundler and check results

Everything looks fine.

The issue only shows up if you then reference that link a second time