Consider switching the definitive openapi file from json to yaml

[narve]

Both yaml and json has some pros and cons. There are two relevant advantages to yaml:

• support for comments
• the format is more compact and has less noise, leading to pull requests / diffs being easier to read.

Especially the second point favours yaml.

Personally I find yaml a bit messy/confusing, but I can get used to it. We can also add a pipeline step to validate the yaml after each commit.

@cdmNSIDE any opinions?

[cdmNSIDE]

Hello Narve,

Sorry for my late reply. Very busy period on many different projects!

Both formats are OK for us.
Our tools usually use yaml files instead of json files, as yaml is more human readable.

[narve]

We should also convert the specification to OpenAPI 3.1 while we're at it.

[narve]

Feel free to provide a PR, @cdmNSIDE, since you are used to working with yaml? Now is probably a good time, since we don't have many open PRs.