Swagger-ui: Newlines in description fields are converted to <br>

[adborden]

Q&A (please complete the following information)

• OS: Linux
• Browser: Chrome
• Version: 67
• Method of installation: npm
• Swagger-UI version: 3.17.0
• Swagger/OpenAPI version: Swagger 2.0

Content & configuration

Example Swagger/OpenAPI definition:
https://his-dev.mmprototype.net/api/v1/api-docs

swagger: '2.0'
paths: {}
basePath: '/'
info:
  title: 'Health Insurance System API'
  version: '1.0.0'
  description: |
    System for storing beneficiaries' health insurance information for the
    Third-Party Liability group. Update active coverage or query the Carrier
    Code Master File.

Describe the bug you're encountering

Newlines in the description fields are being converted to <br>. Since these fields should be treated as markdown, single newlines should be converted to an empty space. Double newlines would be converted to <p>.

For example:

System for storing beneficiaries' health insurance information for the\nThird-Party Liability group. is being converted to System for storing beneficiaries' health insurance information for the <br> Third-Party Liability group.

To reproduce...

Steps to reproduce the behavior:

1. Enter a description with a linebreak.
2. Render with SwaggerUI

Expected behavior

Linebreaks are converted to spaces. Contiguous lines are combined in a single <p>.

Screenshots

[shockey]

Hi @adborden! Thanks for filing an issue.

Below I've traced what's happening with the value in question.

A YAML value's journey

Defined in the document

  description: |
    System for storing beneficiaries' health insurance information for the
    Third-Party Liability group. Update active coverage or query the Carrier
    Code Master File.

Parsed into a JS object by js-yaml

"System for storing beneficiaries' health insurance information for the\n
Third-Party Liability group. Update active coverage or query the Carrier\n
Code Master File.\n
"

Parsed into Markdown by remarkable

Breaks are rendered as newlines (this is configured here), per https://github.com/swagger-api/swagger-ui/pull/3353.

<p>System for storing beneficiaries’ health insurance information for the<br>
Third-Party Liability group. Update active coverage or query the Carrier<br>
Code Master File.</p>

---

So what's going on?

Since these fields should be treated as markdown, single newlines should be converted to an empty space. Double newlines would be converted to <p>.

It doesn't appear that GitHub Flavored Markdown (which Swagger 2.0 calls for) behaves so*.

For example (since we _are_ on GitHub)....
This is a single new line,
and this is another.
As you can see, the lines are not being collapsed.

How to move forward

You can use a different YAML block style to get a different string that will feed into the Markdown renderer.

A folded-strip block style (instead of the literal-clip style you're currently using) should get you what you want:

  description: >-
    System for storing beneficiaries' health insurance information for the
    Third-Party Liability group. Update active coverage or query the Carrier
    Code Master File.

yields the following:

<p>System for storing beneficiaries’ health insurance information for the Third-Party Liability group. Update active coverage or query the Carrier Code Master File.</p>

Which is what I believe you were originally looking for.

Hope this helps! Let me know if you think anything above is in error.

---

*Notably, OpenAPI 3's CommonMark renderer _does_ put the same description value on one line.

[hkosova]

By the way, https://stackoverflow.com/a/21699210 has a detailed reference of various YAML block styles and how they handle new lines.

[adborden]

The line-folding isn't the right solution, because in many cases, the new lines are important and should not be stripped out e.g.

        description: >-
          paragraph 1
          is folded

          paragraph 2
          is folded

          | Value | Description |
          | ----- | ----------- |
          | A     | This is
          | B     | all folded.
          | C     | but shouldn't be.

becomes

paragraph 1 is folded

paragraph 2 is folded

| Value | Description | | ----- | ----------- | | A | This is | B | all folded. | C | but shouldn’t be.

and will not be rendered as an HTML table.

So I think | is the right folding, but you're saying the newline behavior is expected for OpenAPI 2?

[adborden]

BTW, Github Flavored Markdown is a bit funny, because in issues, the lines are folded but in documents like a README, the lines are not folded (you get the behavior that i'm looking for). I'm not sure if this is documented anywhere, but if you have a link to the markdown spec that swagger 2 is using, I would appreciate it.

[DavidBiesack]

Thanks for the details, @shockey Note that _multiple_ Markdown paragraphs (when using >- ) are rendered by Swagger UI with <br>; I think this is incorrect behavior (though not exactly what the OP cited when using | instead of >- ):

This is
paragraph 1.

This is paragraph 2.

is converted to

<p>This is paragraph 1. <br>This is paragraph 2.</p>

not as the expected

<p>This is paragraph 1.</p>
<p>This is paragraph 2.</p>

[shockey]

Changing this over to a bug 😄

We've opted into this behavior:

https://github.com/swagger-api/swagger-ui/blob/b9b4ab20af9d369e02baec3585412fd11ce4bf27/src/core/components/providers/markdown.jsx#L21

Per Remarkable's docs:

breaks: Convert '\n' in paragraphs into <br>.

Disabling this does get rid of the breaks seen in the test definition provided by @adborden.