Closed gilbsgilbs closed 4 years ago
~Mmh, my bad, turns out examples aren't supported in the 04 draft. So while practically useful, this PR may generate schemas with a dangling schemas
property :thinking: . Maybe we could add this as an option then, WDYT?~ Made it an option.
Examples in OAS2/3/JSON Schema are all very different, and it's a hell I continue to be stuck in every day.
https://phil.tech/2020/openapi-examples/
The OAS3 examples object lives outside the schema object, and this package only touches the schema object, so I'm not sure this PR will be salvagble.
Thanks for your reply. That's interesting, I wasn't aware that OAS2 and OAS3 examples were that different.
I'm fine with closing this PR, but I'd like to understand your reasoning a bit more because I don't think I'm in line:
responses
) or as a way to reuse examples by defining them in the dedicated components/examples
section (just like you can already reuse schemas by using a $ref
to components/schemas
). While responses examples look indeed out-of-scope (as this lib only parses schemas as you noted), per-field examples look very supportable to me and is what this PR focuses on. FWIW, I think every single OAS3 and OAS3.1 example linked in your article will work as long as it lives inside the schema (which is the only thing you pass in to this lib anyways).$ref
resolving is already clearly stated as out-of-scope, so the user is already expected to manually resolve any reference to the components/examples
section. Therefore even examples defined outside schemas should actually work in practice.To give you a bit more context on why I need this: I'm trying to generate mocks of the schemas using this library. It can generate random data or just read from a random example.
Thanks for the great work.
After checking again, appears that I'm just wrong. examples
MUST be defined outside schemas and this is a mess. Sorry for the noise.
I think the article I shared explains it better than I could explain it here. It took a long time to write it, but a very brief summary of key points:
Lmk if you have more questions after reading the article. :)
On Tue, Oct 20, 2020 at 10:05, gilbsgilbs notifications@github.com wrote:
Thanks for your reply. That's interesting, I wasn't aware that OAS2 and OAS3 examples were that different.
I'm fine with closing this PR, but I'd like to understand your reasoning a bit more because I don't think I'm in line:
- this library focuses only on OAS3, so let's leave OAS2 aside for the moment.
- you say that OAS3 examples live "outside" the schema object. If I understand correctly, this is a possibility but not a requirement and is only provided as a way to provide examples for non-schema objects (such as responses) or as a way to reuse examples by defining them in the dedicated components/examples section (just like you can already reuse schemas by using a $ref to components/schemas). While responses examples look indeed out-of-scope (as this lib only parses schemas as you noted), per-field examples look very supportable to me and is what this PR focuses on. FWIW, I think every single OAS3 and OAS3.1 example linked in your article will work as long as it lives inside the schema (which is the only thing you pass in to this lib anyways).
- $ref resolving is already clearly stated as out-of-scope, so the user is already expected to manually resolve any reference to the components/examples section. Therefore even examples defined outside schemas should actually work in practice.
- At the end of the day, I think this PR's option behaves in an expected and predictable manner. You pass in an OpenAPI schema (not spec) and it returns a single JSON schema with the examples in it as JSON schema expects them. If you don't want this you can just leave the option disabled and no cats will be harmed. I don't think it will introduce a lot of maintenance burden either (as it probably won't be widely enabled and the spec wont change every few days anyways).
To give you a bit more context on why I need this: I'm trying to generate mocks of the schemas using this library. It can generate random data or just read from a random example.
Thanks for the great work.
— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.
No worries! Our messages swapped in space. Thanks for reading and understanding!
On Tue, Oct 20, 2020 at 11:03, gilbsgilbs notifications@github.com wrote:
After checking again, appears that I'm just wrong. examples MUST be defined outside schemas and this is a mess. Sorry for the noise.
— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.
Another approach that would maybe be more acceptable and that would fill my use-case elegantly would be to add a "hook" option that would get called for each inner schema. Just like the patternPropertiesHandler
option but that would unconditionally get called to let the user patch a schema. Would such option be something you would consider? May I open another PR or do you prefer discussing it in a separate issue?
According to the OpenAPI spec, there are two ways of providing examples for a schema⁽¹⁾:
examples
field with a mapping of Example Objects.example
field which is a single example without further description or summary.As examples aren't supported in JSON Schema Draft 4, this library currently drops the
example
field by default and leaves theexamples
field untouched (which may produce invalid schemas I guess). Since JSON Schema Draft 7 however, it is possible to use the "examples" keyword ⁽²⁾:This PR adds an option to convert OpenAPI's
example
andexamples
fields to JSON Schema Draft 7 examples.⁽¹⁾ https://swagger.io/docs/specification/adding-examples/ ⁽²⁾ https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5