Background

• Unstable order when reading spec from .json file #12

When loading OpenAPI schemas that are encoded in JSON format, Generate will use JSONDecoder to load it as an OpenAPI.Document. This is inconvenient compared to yaml files for two reasons:

1. YAMLDecoder is thread safe, meaning we can use ParallelDocumentParser to decode quicker
2. JSONDecoder does not preserve the ordering of dictionaries that it deserialises resulting in unstable generated output unless you enable isSortingPropertiesAlphabetically

Since most common JSON is also valid YAML, we could save some code and also solve the two problems above by using YAMLDecoder when decoding json files as well.

How

In this PR, I pretty much do just that. In the changes to Generate.swift, I tweak parseInputSpec() so that we check the file format before loading the data and then I remove the call to JSONDecoder so that YAMLDecoder is used regardless of file format.

To support this change, I have also updated some of the test helper methods to require an ext parameter when loading/testing specs since I've also added cookpad.json, which is a really simple Open API schema we use for a small static API that makes up part of our hiring process.

While the schema I committed to the specs is quite small, I can also confirm that we've already been using this approach on a much larger schema for a few months now without issues. In addition, I also converted github.yaml to JSON and re-ran the tests to see if there are any changes - there weren't. If you'd like me to commit convert one of the bigger existing schemas to json as well, do let me know.

One thing to note however is this:

• Fix YAMLDecoder's handling when decoding empty strings into optional types jpsim/Yams#351

With the current versions of Yams, there is one bug that might come up if your schema has empty strings anywhere - they might be mistakenly considered as nil in some cases. This is actually why I didn't update readOptions() to use YAMLDecoder for json configs, since one in the specs falls victim of the bug.

Hopefully that patch will be merged relatively soon though and this won't be too much of a problem. Happy to put this PR on hold though if you'd prefer to wait for the Yams patch to land upstream first.

I merged this patch to our fork anyway.