-
Notifications
You must be signed in to change notification settings - Fork 9.2k
Description
Thank you for merging PR #985 and providing official examples of OpenAPI v3 files! 👏👏👏
Is it possible that api-with-examples.yaml has errors?
I am asking because I validated all four examples/v3.0/ files with JSON Schema created by @timburks and @MikeRalphson. The JSON Schema validation is OK on petstore-expanded.yaml, petstore.yaml, and uber.yaml, but fails on api-with-examples.yaml.
Validation fails on content examples - there are four examples in the file, the first of which is defined on line 16:
content:
application/json:
examples:
- {
"versions": [
{<...>}, {<...>}]
} Media Type Object can define examples in two ways:
example(singular) - inlines example text directly (Anyin JSON Schema);examples(plural) - uses the Example Object, which also provides additional information, such as example name, summary, or description.
The problem is that api-with-examples.yaml defines examples with examples, but inlines them as if they were defined with example.
In my understanding of the spec, api-with-examples.yaml should be corrected:
- Either
exampleskeyword should be replaced byexample:
content:
application/json:
example:
{
"versions": [
{<...>}, {<...>}]
} - Or, we should use a real named example object where the example snippet is defined in
value(orexternalValue):
content:
application/json:
examples:
versions-example:
summary: Versions Example in JSON
value: {
"versions": [
{<...>}, {<...>}]
} Can you please clarify the usage of the examples keyword in api-with-examples.yaml?