Skip to content
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

Merged
merged 5 commits into from Jul 3, 2020
Merged

Add literal style support for OpenApiYamlWriter #481

merged 5 commits into from Jul 3, 2020

Conversation

foriequal0
Copy link
Contributor

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 to document.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.

@msftclas
Copy link

msftclas commented May 23, 2020

CLA assistant check
All CLA requirements met.

@darrelmiller
Copy link
Member

@foriequal0 Thank you for this submission. This is a great addition. I am going to try it out and get it released ASAP.

@darrelmiller
Copy link
Member

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?

@foriequal0
Copy link
Contributor Author

I also found that "clip" indicator introduces a trailling newline even if the original input doesn't have one.
I'll push more commits to handle chomping indicator correctly.

@foriequal0
Copy link
Contributor Author

Also I realized that I don't have to preserve linebreaks. The spec clearly 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

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.
@darrelmiller darrelmiller added this to the 1.3 milestone Jul 3, 2020
@darrelmiller darrelmiller merged commit 30d9969 into microsoft:vnext Jul 3, 2020
@foriequal0 foriequal0 deleted the literal-style branch July 3, 2020 02:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants