microsoft
Support of comments in yaml files?
I am currently working on a component that reads an OAS 3 file, enhances it and writes it back. Unfortunately all comments in the original file get lost then, as they are currently ignored. Do you have any ideas how to solve it with this component?
Example:
...
### this comment about the path section gets lost
path:
...
One solution would be to convert comments to extensions on read, and re-write them when we write out in YAML. This would only work for objects that support extensions. Not sure if that partial solution would cause more aggravation than not supporting at all.
The other option would be for our DOM to support comments natively that are not part of OpenAPI document. We wouldn't be able to export those as JSON.
I would suggest using the summary/description properties as much as possible and create additional x-internalComment for text that you don't want to appear in documentation.
To be honest, I'm not sure if comments are actually allowed as OpenAPI limits the use of YAML to only things that comply with the JSON Schema subset. I don't know how that constraint affects YAML comments.
I'm not sure if comments are actually allowed as OpenAPI limits the use of YAML to only things that comply with the JSON Schema subset. I don't know how that constraint affects YAML comments.
This is a good hint. Thank you very much. In fact YAML does support comments, but JSON does not and therefore OpenAPI probably does not.
So it might be more useful to implement comments in the source files as errors as well.
On the subject of errors: It would be nice if the diagnostic object supported error levels like "Warning", "Error". This comment topic would then be from my point of view of the level "Warning" and could then be ignored during processing. Furthermore, it would be very helpful if the errors were categorized or numbered. Then they could be processed more easily instead of having to parse the strings.