YAML comments are stripped

[bbrks]

I have no idea if this is intentional, or just a difficult problem to solve, but comments are stripped from YAML OpenAPI specs.
This becomes a little bit problematic when the comments are meaningful to the openapi writer and help maintainability.

E.g:

# asdf
info:
  title: title
  description: description
  version: "3.1.0" # comment

Becomes

info:
  title: title
  description: description
  version: 3.1.0

[thim81]

@bbrks Sadly enough, there is no way to keep the comments.
We are using a YAML parsing library and all YAML libraries strip the comments by default as soon as they serialise the content of the YAML file.
openapi-format uses https://github.com/stoplightio/yaml for parsing the YAML file, so perhaps you can open an issue to see if they have a solution for the comments?

If you find a manner, please let me know, since I struggle with the comments being removed as well.

A possible work-around is that you format the file and write the formatted file next the original file and do a diff of both files.

[thim81]

Update: Stoplight YAML-ast-parser introduced the option to preserve comments on YAML docs, stoplightio/yaml-ast-parser#6

Will need some more investigation

[thim81]

hi @bbrks

We just release v1.23.0 which provides the option --keepComments which keep the YAML comments in a file.

Closing this issue.
If you're still experiencing problems, please feel free to reopen this issue or create a new one. Thanks for taking the time to report it!