New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add literal style support for OpenApiYamlWriter #481
Conversation
@foriequal0 Thank you for this submission. This is a great addition. I am going to try it out and get it released ASAP. |
There is just one issue that concerns me here. Using this input: openapi: 3.0.0
info:
title: asdads
version: 1.0.0
paths:
/:
get:
description: |
Hello
World
responses:
200:
description: ok the output is openapi: 3.0.1
info:
title: asdads
version: 1.0.0
paths:
/:
get:
description: |+
Hello
World
responses:
'200':
description: ok If this output is used as input then the "keep" chomping indicator will cause an extra newline to be introduced. Would it not be better to use the "clip" chomping indicator as the default output? |
I also found that "clip" indicator introduces a trailling newline even if the original input doesn't have one. |
Also I realized that I don't have to preserve linebreaks. The spec clearly says:
I'll remove clunky line break handlings too. |
The YAML 1.2 spec says > Line breaks inside scalar content must be normalized by the YAML processor. Each such line break must be parsed into a single line feed character. The original line break format is a presentation detail and must not be used to convey content information. https://yaml.org/spec/1.2/spec.html#id2774608 Not preserving newlines simplifies the `OpenApiYamlWriter.WriteValue` and reduces number of test cases.
The Block chomping indicators affects how the final line break is interpreted. So use "strip" when the value doesn't ends with a line break, "clip" when the value ends with a line break, and "keep" when the value ends with multiple line breaks.
OpenAPI allows
description
to be written in Markdown. Markdown descriptions can be multiple lines.Current
OpenApiYamlWriter
escapes all control characters and joins and serializes them in one line.I read description from external
README.md
file, and put it todocument.Info.Description
, and publishes the generated OpenAPI document.Users can
diff
with previous versions of documents to track any public changes.However, it is quite daunting when you have to look these long concatenated Markdown description to find diffs.
With literal style block scalar, I can preserve my line breaks of
README.md
as is.