Skip to content

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

Closed
MikeRalphson opened this issue Mar 1, 2017 · 11 comments
Closed

Comments

@MikeRalphson
Copy link
Member

MikeRalphson commented Mar 1, 2017

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:

SHOULD be in the correct format as specified [in the] parameter encoding

I'm probably missing something.

@darrelmiller
Copy link
Member

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.
We have made examples and example mutually exclusive, so for tooling it shouldn't be much more than an extra if statement to handle both properties.

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.
The example has been left in for schemas. Maybe that isn't needed any more now that example objects are now reusable components.

It is possible there could be some streamlining, but if we were to remove example I think it would be more for reducing conceptual complexity, rather than making tooling easier.

@fehguy
Copy link
Contributor

fehguy commented Mar 3, 2017

@MikeRalphson does that answer your question? If so please close...

@MikeRalphson
Copy link
Member Author

@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 servers, requestBodies etc.

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.

@fehguy
Copy link
Contributor

fehguy commented Mar 3, 2017

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.

@MikeRalphson
Copy link
Member Author

I'll have a hunt through the issues.

Certainly nobody was creating work just for the sake of creating work.

I hope I didn't come off as remotely suggesting that.

@fehguy
Copy link
Contributor

fehguy commented Mar 3, 2017

No problem at all. I believe the examples arguments were around the requestBody changes

@MikeRalphson
Copy link
Member Author

Looks like Issue 800 is the most relevant. In which @DavidBiesack expressed a preference for the oneOf example / examples. I could find no other requests for this specific feature in the issues.

@MikeRalphson MikeRalphson changed the title Clarify thinking behind .example object and .examples array ? Please reconsider duality of .example object and .examples array ? Mar 3, 2017
@DavidBiesack
Copy link
Contributor

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.

@MikeRalphson
Copy link
Member Author

Understood, but I still contend that it doesn't smell like any other part of the OpenAPI 3 spec. ;)

@DavidBiesack
Copy link
Contributor

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.)

@willdady
Copy link
Contributor

I agree with @MikeRalphson. To me this seems overly verbose when a single item examples array would suffice. If the argument for having both is for 'backwards compatibility' then I think this needs to be revisited since 3.0 is strictly not compatible with 2.0. I would argue the cognitive load of understanding the difference outweighs any tediousness of coding an array (literally adding a - in yaml, json slightly more work sure).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants