This is a minor nitpick but as someone unfamiliar with the OpenAPI specifcation and yaml until now, I found it confusing at first. There is inconsistent usage of quotes in the yaml examples in the 3.0.2 specification (and presumably earlier).
Specifically, there are places where the yaml examples have content
'application/json' and other spots where it has
application/json. Same confusion applies to other content values. A notable example is the file uploads section where it has content
application/octet-stream without quotes,
'image/png' with single quotes, and then
multipart/form-data without quotes.
I also noticed inconsistencies with the
$ref: value where for example it has
$ref: "#/components/schemas/Pet" with double quotes and
$ref: '#/components/schemas/SomePayload' with single quotes.
Is there a best practice? Reading the examples it wasn't immediately clear to me when I should quote vs not quote, and if single quote vs double quote is more standard.
@ioggstream sorry to come back to this after so long. I don't think this recommendation should be in the spec itself, as people should be free to quote (and indent etc) their OpenAPI documents in any way which is valid.
However, a PR to a (new)
README.md file in the
examples subdirectory would I think be a good idea so our own examples can aim for consistency.