chore: use JSON instead of YAML for openapi generation

[leseb]

What does this PR do?

JSON has a few advantages over YAML in this context:

• No extra dependency: Removed ruamel.yaml; using the standard library json module.
• Simpler code: No YAML formatting configuration (indent, flow style, string presentation, etc.). JSON serialization is straightforward.
• Faster generation: JSON serialization is typically faster and more predictable than YAML formatting.
• Native OpenAPI format: JSON is the native OpenAPI format. Many tools prefer JSON, reducing potential compatibility issues.
• Better tooling support: JSON is widely supported. Tools like oasdiff, OpenAPI validators, and code generators work well with JSON.
• Fewer formatting edge cases: YAML can have edge cases (multiline strings, special characters, quoting, scalars etc). JSON avoids these.

All the tools consumming the YAMLs have been updated namely oasdiff for conformance tests, docusaurus config and the genrator.

Test Plan

CI conformance tests.

This is foundation work to ease #3944 too.

[ashwinb]

I really do disagree with this quite a bit. Not only are OpenAPI specs widely available in YAML, YAML tends to be far more readable and consumable than JSON. It is reasonable to say we can produce both.

[leseb]

I really do disagree with this quite a bit. Not only are OpenAPI specs widely available in YAML, YAML tends to be far more readable and consumable than JSON. It is reasonable to say we can produce both.

Yes, it's more readable / consumable. But in practice, by whom? Who reads it despite stainless or other programming tools? Do humans really look at it?

[ashwinb]

Yes, it's more readable / consumable. But in practice, by whom? Who reads it despite stainless or other programming tools? Do humans really look at it?

• We certainly consume it on each PR when things change. How a downstream type changes the final spec is not sometimes apparent and the diff on YAML is quite informative and succinct to understand it.
• Stainless as far as I know still needs the YAML as its input.
• Finally, I don't see why we need to remove it at all. If something else needs JSON, sure we can have it, but why is removing the ruamel.yaml dependency important?

[leseb]

@Mergifyio rebase

[leseb]

Yes, it's more readable / consumable. But in practice, by whom? Who reads it despite stainless or other programming tools? Do humans really look at it?

• We certainly consume it on each PR when things change. How a downstream type changes the final spec is not sometimes apparent and the diff on YAML is quite informative and succinct to understand it.

If you feel like YAML is helpful during code review, I'll stop here then :)

• Stainless as far as I know still needs the YAML as its input.
• Finally, I don't see why we need to remove it at all. If something else needs JSON, sure we can have it, but why is removing the ruamel.yaml dependency important?

It's not the just ruamel.yaml, it's more all the boilerplate code we have in the generator to configure the YAML output. JSON is much easier on that front.

Anyways, I can live witht that I guess.

[ashwinb]

If you feel like YAML is helpful during code review, I'll stop here then :)

yes I most definitely look through YAML changes during code review and have spotted issues over time due to this review.