Open michaelgwelch opened 3 years ago
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:
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
example:
$ref: /link/to/file
Everything looks fine.
The issue only shows up if you then reference that link a second time
Per https://github.com/OAI/OpenAPI-Specification/issues/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
underexample
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 anexample
alone. (unless the tool is attempting to make$ref
under anexample
just "work", in which case more work would be needed at theexample
sites.)Note: I wasn't using
components
, but even when I did update my files to usecomponents
correctly, it just makes the problem slightly worse. In this case the reference file gets inlined intocomponents
as you'd expect and then every other referencing site ends up with something like the screenshot above.