Swagger-ui: Margins for p blocks in Operation notes are 0, and provide no spacing between paragraphs

[dotasek]

| Q | A
| ------------------------------- | -------
| Bug or feature request? | Bug
| Which Swagger/OpenAPI version? | 2.0
| Which Swagger-UI version? | 3.9.3
| How did you install Swagger-UI? | Downloaded from git, and used included dist directory
| Which browser & version? | Chromium 63.0.3239.132
| Which operating system? | Ubuntu 14.04

Configuration (browser query string, constructor, config.yaml)

  spec:{
  "swagger" : "2.0",
  "info" : {
    "description" : "Something in a line  \n  \nAnd something in a **new** line.",
    "version" : "V2.0.0",
    "title" : "Newline behavior"
  },
  "host" : "localhost:1234",
  "tags" : [ {
    "name" : "Tag1"
  } ],
  "schemes" : [ "http" ],
  "consumes" : [ "application/json", "application/xml" ],
  "produces" : [ "application/json", "application/xml" ],
  "paths" : {
    "/" : {
      "get" : {
        "tags" : [ "Tag1" ],
        "summary" : "operation",
        "description" : "Something in a line  \n  \nAnd something in a **new** line.",
        "operationId" : "getVersions",
        "produces" : [ "application/json" ],
        "parameters" : [ ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "type" : "object",
              "additionalProperties" : {
                "type" : "array",
                "items" : {
                  "type" : "string"
                }
              }
            },
            "headers" : { }
          }
        }
      }
    },

  },
  "definitions" : {
  }
}

?yourQueryStringConfig=here

Expected Behavior

When the UI renders the description "Something in a line \n \nAnd something in a **new** line.", it should appear as follows:

Something in a line

And something in a new line.

Current Behavior

The markdown parser appears to correctly break text into <p> blocks, but the spacing between those blocks is zero, so the text doesn't have the expected space between paragraphs and appears as follows:

Something in a line
And something in a new line.

Possible Solution

I edited the css file in my dist directory directly, to include a 10px bottom margin instead of the 0 margin that currently exists:

...
swagger-ui .opblock-description-wrapper p,.swagger-ui .opblock-external-docs-wrapper p,.swagger-ui .opblock-title_normal p{font-size:14px;margin-bottom:10px;font-family:Open Sans,sans-serif;color:#3b4151}
...

Context

This issue has made it impossible to make well structured operation notes on endpoints that require more complex descriptions. The descriptions appear more or less as a solid block of text instead of having easily discernable paragraphs.

[heldersepu]

The description accepts full html maybe you can try formatting like that:
Here I are a couple of examples:
http://swashbuckletest.azurewebsites.net/swagger/ui/index#/ApiExplorer/ApiExplorer_Get
http://offleaseonly.azurewebsites.net/swagger/ui/index#/Cars/Cars_Get

[dotasek]

Hi Helder; I understand that a mix of markdown and html might provide a workaround, but the appearance I'd expect from CommonMark would be absent, and that could provide frustration for people documenting our API.

If it would behave as expected for a CommonMark interpreter, I could simply link to CommonMark, and not have to have to give any additional notes to our documentation writers about special cases and workarounds.

[heldersepu]

Let's test that, let's see how much markdown is supported...

[heldersepu]

Looks like the markdown formatting is currently only for response-col_description__inner:
https://github.com/swagger-api/swagger-ui/blob/e531c40356a58965a6199924e9af21e4282cc02c/src/style/_layout.scss#L549

The description is under opblock-description

[dotasek]

I'm not proficient in JavaScript or css; any solution which gets me to the expected behaviour would be great. I can see that the relevant section is enclosed in a markdown div, so I'm not sure why my edit of the css changes anything, but it does.

I can also confirm that the issue is the same in Firefox 58.0 under Ubuntu as well.

[webron]

What's interesting is that the definition's general description renders properly, while the operation description offers zero space. Definitely a bug.

[jaufgang]

Yeah, this seems to have been set explicitly in the css:

.swagger-ui .opblock-description-wrapper p,
.swagger-ui .opblock-external-docs-wrapper p, 
.swagger-ui .opblock-title_normal p {
    font-size: 14px;
    margin: 0;
    font-family: Open Sans,sans-serif;
    color: #3b4151;
}

Probably the margin was set to 0 in order to remove whitespace at the top and bottom of single-paragraph descriptions, while failing to take into account the possibility of multi-paragraph desacriptions. A solution would be to remove the top and bottom margins for the first and last paragraphs in using the :first-child and :last-child selectors. (See: https://css-tricks.com/snippets/css/remove-margins-first-element/)

[shockey]

Looks like we're setting 1em vertical margins on <p> elements now:

I'm open to more if it makes sense visually, but since the original issue was about the margin being 0 I'm going to close this out.

Thanks everyone!