Cleaning up samples, parity between yaml and json - Close #559

[jharmn]

Hopefully addresses issues identified in #267
All samples run through swagger-tools validate with no errors (unless I missed one ;))

yaml2json and json2yaml used to convert between formats to ensure parity.

[webron]

You mean the npms or their online variants like http://yamltojson.com/?

[mohsen1]

The conversation from yaml to json should be part of build and we should never touch the json manually

[jharmn]

@webron the npms.
@mohsen1 the only reason I did it the other way, is there were samples existing in both dirs that weren't in the other.

[jharmn]

@mohsen1 but I agree that would be a great enhancement.

[webron]

Well, I definitely don't have time now to add it to the build process, unfortunately.

In my experience, the online versions produce subpar conversions, where http://i-tools.org/unserialize produced much better results. Not sure if/what cli tool they have. In any case, I'll have to go over the PR and check it, but will get around to it only next week.

[jharmn]

@webron There are solid NPM packages for this (I haven't had any issues yet, forgive my ignorance if there are issues):
https://www.npmjs.com/package/yaml2json
https://www.npmjs.com/package/json2yaml

I'll see if I can get some time to add it to the build next week.

[webron]

@jasonh-n-austin - yes, but if those npms are the same one used in the online variant, then solid or not, they produced imperfect conversions (specifically from json to yaml). Since yaml is a superset of json, you can basically have "json" values to properties (like arrays and such), and to me, as samples, that doesn't teach users what the yaml should look like. Does it work? yes. Is it what we want to teach? Probably not. Keep in mind though that I haven't looked at your conversions yet, I'm just speaking from experience of converting all the JSON in the spec itself to YAML.

And please don't get me wrong, I'm so happy you took the time to submit this PR, it is a huge help.

[jharmn]

@webron no offense taken...definitely let me know if you see something weird, I'd love to know if I'm using sub-standard stuff 😰

[jharmn]

@webron ping!

[webron]

@jasonh-n-austin - sorry, fairly swamped right now. I'm going to allocate some time specifically for the spec issues, especially to fixes to the schema, samples, and tests, but due to my upcoming trip it won't be for at least a week. Some great PRs are pending.

If this is more urgent to you, please let me know.

[jharmn]

Rebased and ran gulp yaml2json to ensure JSON is generated. Reviewing to see how valid this still is, looks like there's been updates to samples here and there.

[jharmn]

This existed in YAML, but not JSON examples.

[jharmn]

@webron I was thinking we should revisit having accurate examples, as we look to add functionality. Updating these with new features will be pretty important, and it would suck if they weren't working in the first place.
P.S. It seems like we need a README in examples on how to change (edit YAML, run gupl yaml2json) for contributors.

[webron]

@jasonh-n-austin -yeah, time to merge it, following #559 as well.

As for the examples in general, it should be part of the next spec development process. If we can automate conversions and so on, all the better (so we can agree the source for the samples is YAML for example).