Update Examples Object #1028
Update Examples Object #1028
Conversation
Clarify that Examples Object may be used instead of Example Object. Show JSON examples as well as YAML Clarify the $ref values used in examples to remove ambiguity. These are not references to external JSON/XML/TXT resources, but rather are references to reusable examples in the current OpenAPI definition or in an external OpenAPI definition's components/examples This does not yet address issue OAI#488 but cleans up Examples Object a bit, which is needed whether we alter the OAS as per OAI#488 .
versions/3.0.md
Outdated
| @@ -1128,20 +1128,20 @@ A request body with a referenced model definition. | |||
| "schema": { | |||
| "$ref": "#/components/schemas/User" | |||
| }, | |||
| "examples": [ "http://foo.bar/examples/user-example.json" ] | |||
| "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.json" ] | |||
There was a problem hiding this comment.
I assume user-example.json is a property name for examples? Should user-example.json be application/json?
There was a problem hiding this comment.
yes. This was carried over from the original, but I can change the names if that will help avoid confusion.
There was a problem hiding this comment.
The naming is definitely confusing, to me at least.. user-example.json reads like a file name.
There was a problem hiding this comment.
ok, good feedback - I've updated the PR, and also added a missing JSON block, and also named the /components/example/ items more uniformly.
I also fixed some cases where the spec
had /components/schemas/pet in some places, /components/schemas/Pet in others.
Remove .json, .xml other extensions from examples so they do not look like file/resource names Use components/examples/camelCase not hyphenated-names uniformly
| `example` and `examples` are mutually exclusive. | ||
|
|
||
| Anywhere an `example` may be given (including in the Examples Object array), | ||
| a JSON Reference MAY be used, with the |
There was a problem hiding this comment.
For consistency, we should use Reference Object (linkfied) instead of JSON Reference.
There was a problem hiding this comment.
I'm also going to move this paragraph to Example Object which is a better place for it.
| @@ -2365,42 +2370,147 @@ for the value that it is accompanying. Tooling implementations MAY choose to | |||
| validate compatibility automatically, and reject the example value(s) if they | |||
| are not compatible. | |||
|
|
|||
| Here is a single `example` in a model [Schema Object](#schemaObject): | |||
There was a problem hiding this comment.
Minor nit, is "single" necessary here? Basically, you're saying "Here is an example within a model". Thoughts?
There was a problem hiding this comment.
I'm going to convert it to examples (and drop "single) since this is the Examples Object section, not Example Object.
| $ref: "#/components/examples/identity" | ||
| ``` | ||
|
|
||
| Below is an `examples` array in a [Request Body Object](#requestBodyObject), |
There was a problem hiding this comment.
Same as above, you've already documented examples to be an array so it seems unnecessary.
| ``` | ||
|
|
||
| Below is an `examples` array in a [Request Body Object](#requestBodyObject), | ||
| showing two in-line examples and references |
There was a problem hiding this comment.
"in-line" should be "inline".
|
Thanks for being patient with the nitpicks. :) |
Remove .json, .xml other extensions from examples so they do not look like file/resource names Use components/examples/camelCase not hyphenated-names uniformly Move key descriptions (for $ref, schema constraints) and Example Object Example from Examples Object into Example Object. Include some examples that are just string values (ZipCode), an object (Address), and XML (SimpleXmlAddress) Improve examples for Example Object, show definitions in components/examples. Remove overly verbose examples from Examples Object
|
Anyone willing to review and merge this (before the text has diverged too much making merge difficult)? |
|
May not be needed if the proposal in #1035 is accepted. |
|
Closing - #1035 addressed the changes in this PR |
Clarify that Examples Object may be used instead of Example Object.
Show JSON examples as well as YAML
Clarify the $ref values used in examples to remove ambiguity.
These are not references to external JSON/XML/TXT resources, but
rather are references to reusable examples in the current OpenAPI definition
or in an external OpenAPI definition's components/examples
This does not yet address issue #488 but cleans up Examples Object
a bit, which is needed whether we alter the OAS as per #488 .