-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add examples object #636
Add examples object #636
Conversation
@@ -1152,6 +1152,51 @@ name: pet | |||
description: Pets operations | |||
``` | |||
|
|||
#### <a name="examplesObject"></a>Examples Object | |||
|
|||
Anywhere an `example` may be given, allow a $ref object. This does mean that `example` can be either a string primitive or an object, like `additionalProperties`: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a change to the 2.0 behavior, where the example property of a model is of the same type as what the model described. (I.e. type: object
means it would be an object, type: string
means it is a string, type: number
means it is a number.) Now it seems to be a string containing formatted JSON (or a reference to such)?
If this is intentional, that needs to be updated too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ePaul actually, in 2.0 it is the default
field value has to be the same type as it's 'container' (be it a parameter or a model property). The examples have on such constraint.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@webron Maybe I'm misunderstanding this. Example Object (for responses):
The name of the property MUST be one of the Operation produces values (either
implicit or inherited). The value SHOULD be an example of what such a response
would look like.
The example for this (with a JSON object) seem to indicate that this is an instance matching the schema.
In the schema object we have:
Field Name Type Description example Any A free-form property to include a an example of an instance for this schema.
Here too, I would understand (and the examples agree) that this usually include the JSON value, not a string representation thereof. (While it might not be a "constraint", given the type "Any", the text + examples strongly suggest this.)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ePaul - when writing the spec, while making mistakes here and there, I've taken great care to word things as they are. Type Any
means just that - any valid JSON value would fit there, regardless of what it relates to. The word SHOULD
is used on purpose and not the word MUST
. The spec really does not enforce any sort of constraint here, and I don't think it should (for a few reason).
Going back to the default
field value, you'll see that it uses a stronger restriction saying it MUST
follow the type assigned to its container.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@webron Okay, maybe the spec writers meant not to put a restriction here (I guess you were there – I was not), but then I don't think this is a good idea to allow just "anything at all".
It should clearly define how the examples are meant to be used.
Allowing just strings (or refs to such) now is also okay, as long as it is made explicit.
I'm a bit confused by this. Is this meant to add Also, adding |
@OAI/tdc please approve or reject |
a) this is awesome and has a big 👍 from me |
@darrelmiller it's a bit ugly now, but technically the approach in 2.0 was that non-json complex values would be pretty much strings. The use of a reference doesn't really change that (you won't be able to magically reference an XML document because it would result in an invalid JSON). As for the multiple schema - not necessarily. 2.0 has a single schema for JSON and XML for example, although it's obviously limited. With that, it would still be possible to provide multiple examples. This may change when we tackle the content negotiation (and thus supporting multiple schemas). 👍 from me for the proposal, but the PR does not cover the changes that need to be made in the spec itself. I can expand the PR if the proposal itself is accepted by the @OAI/tdc. |
|
||
In locations where the field being provided an `example` is a scalar value _or_ has it's content-type definition determined by a higher-level construct (a response payload, for example, uses the `produces` attribute to select the correct message format), the plural `examples` shall be used, and the payload format be specified as a key to the example. | ||
|
||
In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling vendors may choose to valide compatibility automatically, and reject the example value(s) if they are not compatible. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@fehguy "choose to valide" => "choose to validate"
@fehguy a point of confusion: you updated the "Examples Object" section (https://github.com/OAI/OpenAPI-Specification/blob/issue-544/versions/3.0.md#examples-object), but reference |
thanks @jasonh-n-austin. I'm going to make a note to clarify the documentation on this and we can close this out. |
👍 |
1 similar comment
👍 |
Fixes #544
DO NOT MERGE--needs documentation updates.