Consider switching the definitive openapi file from json to yaml

euniversal / umei-api-specification

UMEI API specifications

Apache License 2.0

3 stars 0 forks source link

Open narve opened 2 years ago

narve commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

narve commented 2 years ago

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.