-
Notifications
You must be signed in to change notification settings - Fork 9.1k
Please reconsider duality of .example object and .examples array ? #953
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
Comments
From my perspective there wasn't a strong motivation for keeping the "example" property. It was primarily for simplicity and backward compatibility. We have added a fair amount of complexity to some objects, there was some reluctance to force example arrays on everyone. The examples/example have been added to the content object, so when tooling people implement it, it will automatically work for requestBody, responses, callbacks, links, complex parameters. It is possible there could be some streamlining, but if we were to remove |
@MikeRalphson does that answer your question? If so please close... |
@fehguy @darrelmiller Thanks for the response. I would however question the need for "backwards compatibility" when there has explicitly been a breaking change in the version of the specification. There seems to be no other examples of such mental backwards compatibility around I'm not wholly convinced by the simplicity argument either I'm afraid, there is one spec to create, but many tools, each of which would have to take this wrinkle into account. If it looks like a wart, and sounds like a wart... If it is unlikely to change, or is still up for consideration outside the public sphere of GitHub issues, then yes, please close. |
Well this was actually requested and should hopefully be captured in the issues. Certainly nobody was creating work just for the sake of creating work. |
I'll have a hunt through the issues.
I hope I didn't come off as remotely suggesting that. |
No problem at all. I believe the examples arguments were around the |
Looks like Issue 800 is the most relevant. In which @DavidBiesack expressed a preference for the |
I'll just chime in that my preference is strictly for ease of use of the API author. I think many cases one example is sufficient and using example: is very easy whereas using examples: and coding an array is just more tedious. I think tooling can pretty easily account for this and do the transformation for us; that's what computers are good at. Again, this is just my preference - -I tend to side on ease of use for people using OAS. |
Understood, but I still contend that it doesn't smell like any other part of the OpenAPI 3 spec. ;) |
It is a personal preference, I'm not strongly opposed to more uniform implementation (i.e. just examples: [ ]). (I do not think that preserving singular example: syntax just because it was singular in 2.0 is important here.) |
I agree with @MikeRalphson. To me this seems overly verbose when a single item |
Uh oh!
There was an error while loading. Please reload this page.
Please could someone provide some background on the decision to have both .example and .examples[] properties on the requestBody, responses and schemas?
It seems to me this might unnecessarily complicate documentation tooling, while the alternative is simply using a one-element array if only one example is provided. Extending an existing definition with a single example would involve more editing when adding a second one.
An operation object does not have both a .tag and .tags[] properties.
I also found the following wording confusing:
I'm probably missing something.
The text was updated successfully, but these errors were encountered: