Don't remove newlines from OpenAPI descriptions

[silas]

Update protoc-gen-openapi to not remove newlines from descriptions as this breaks markdown formatting.

[timburks]

Hi @silas, thanks for noting this! YAML has options for configuring how newlines are treated in strings (reference). The files affected by your change used "literal" style, where newlines were kept. We could consider instead writing strings in "folded" style, where newlines in the YAML file are replaced with spaces. Do you think that would fix the Markdown problems that you're observing? (I'm concerned that single-line strings could be very long and make the generated specs hard to read)

[silas]

Hi @silas, thanks for noting this! YAML has options for configuring how newlines are treated in strings (reference). The files affected by your change used "literal" style, where newlines were kept. We could consider instead writing strings in "folded" style, where newlines in the YAML file are replaced with spaces. Do you think that would fix the Markdown problems that you're observing? (I'm concerned that single-line strings could be very long and make the generated specs hard to read)

I think the "folded" style is still going to break markdown.

I'm not 100% sure I understand the single-line strings problem. Right now gnostic removes all the newlines, which effectively creates a long single-line string, which is more difficult to read (at least to me) in raw YAML form and via tooling.

Is there a specific tool you use which doesn't render the new style well? I'm happy to take a look.

You can try the below code example via the Swagger Editor to see how different styles render (or see the screenshots below).

openapi: 3.0.3
info:
    title: Example
    version: 0.0.1
paths:
    /example:
        get:
            description: Some example.
            parameters:
                - name: example
                  in: query
                  description: |-
                    This is an example description.
                    
                    We want some interesting content here.
                    
                    Some examples:
                      - Example 1
                      - Example 2
                      - Example 3
                      
                    ## Code

                        Some block of code.
                  schema:
                    type: string
            responses:
                "200":
                    description: OK

Current PR (literal)

Current PR (folded)

Main branch (newlines replaced with strings)

[morphar]

@silas I think this looks good and agree that it's much more readable.
And very nice, not breaking Markdown :)

@timburks could you elaborate on your concerns? I don't think I quite understood either.
Is the issue that there will be more lines in the YAML file?
I can see how long descriptions could add up to the total amount of lines.

I guess it's a question of balancing readability of the "code" of the YAML files and the readability of the output in tools like Swagger editor.

Would a better solution be to not remove the newlines (or replace with \n), but keep the less readable single line definition?

It doesn't seem to break any conversions between formats, unless there's something we haven't thought of.