Swagger-ui: Markdown not rendered

[jonathanhuet]

In responses, the markdown is not rendered

Current result:

You can see that the MD is not rendered

Expected result
the MD is rendered. Image from the editor , but rendering was similar in previous version of Swagger UI

How to reproduce

Paste this code in YAML API spec

responses:
  Error403:
    description: |
      ** Forbidden **

      Possible values

      | Error Name | Error Message  | 
      |--------|---|---|
      | FORBIDDEN | Forbidden  |
    schema:
          $ref: '#/definitions/Error'

And use it as response

Notes

• Same behavior seems to occurs in other parts of the API spec interpretation ( tested in API call description and reproduced )

[jostick]

I have the same issue with markdown in property descriptions. The old Swagger UI did render markdown in situations like this:

AuthorizationError: type: object required: [ code ] properties: code: type: string description: | A value that can be used for error handling * **InvalidListingClaim** Listing claim JWT could not be parsed or is expired. Please get a new claim. * **PermissionDenied** User is not authorized to modify this listing enum: - InvalidListingClaim - PermissionDenied

The old Swagger UI did render the markdown as expected, but Swagger UI 3 displays it as plain text.

[jejohnsonjr]

Any fix for this? I have a bunch of Swagger files with MarkDown that I need to display in Swagger UI 3

[webron]

Not yet. Contributions are welcome.

[ralfhandl]

Will Swagger UI 3.x support Github Flavored Markdown (GFM) to fulfill the Swagger 2.0 specification, or will it support CommonMark to fulfill the OpenAPI 3.0 specification?
Or both?

Background of the question is that @jonathanhuet's example uses GFM table markdown with pipe symbols which isn't part of CommonMark.

[webron]

No explicit plans. Likely GFM for 2.0 and CommonMark for 3.0.

[michaelkourlas]

Markdown is also not supported in definitions:

swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
paths:
  /:
    get:
      description: GFM is supported here. **bold** *italic*
      responses:
        '200':
          description: OK
          schema:
            $ref: "#/definitions/TestType"
definitions:
  TestType:
    type: object
    description: GFM is not supported here, though it should be. **bold** *italic*

[DavidBiesack]

I'm seeing Markdown conversion work OK in descriptions in models, responses, etc. in 3.6.1
However, Markdown is still not being processed in descriptions for headers in responses.

[lcahlander]

It is not being rendered for a request body schema property description.

"/upload-all": {
    "get": {
        "requestBody": {
            "content": {
                "application/x-www-form-urlencoded": {
                   "schema": {
                       "type": "object",
                      "properties": {
                          "my-attachment": {
                              "type": "binary",
                              "description": "## The uploaded files\n\n* The map's keys represent the filenames of each file uploaded\n* The map's values are themselves maps too, let's call this an \"entry map\"\n* The entry map contains two keys, a content-type and a body\n* The value for content-type is the Content Type of this particular file\n* The value for body is the Content Body of this particular file as a binary() item"
                          }
                      }
                  }
              }
          }
      },
     "description": "Upload zip file to the server",
     "responses": {}
    }
},

[john3300]

@webron

No explicit plans. Likely GFM for 2.0 and CommonMark for 3.0.

There is now a GFM extension for CommonMark that could be utilized to get table support in OAS 3 spec files: https://github.com/github/cmark-gfm

[shockey]

FYI to commenters and readers, we've enabled support for GFM tables on top of Commonmark for OpenAPI 3: https://github.com/swagger-api/swagger-ui/pull/5224

The original issue here is still open.

[mschmidt98]

I don't know, if this is located correctly here, but since this issue is still open, I'll just try..

Our API accepts a pre-hashed password, so we need to display the example code to create this hash in our specification.
The yaml file of the model our login accepts looks like this:

password:
  description: "Der Hashwert des Kennwortes des Benutzers. Encoding des Passwortes: UTF-8, Hashverfahren: SHA512, Salt: \"HABh2b3czM4jhBXN3rfrMmWMXJVCMnLQTPYFmmdanKEFUgd6RzzvBXDWfyqgBVvq\", Encoding der Bytes des Hashes: Base64.\n\nC#-Beispielcode:\n```\nusing (var hmac = new System.Security.Cryptography.HMACSHA512(System.Text.Encoding.UTF8.GetBytes(\"HABh2b3czM4jhBXN3rfrMmWMXJVCMnLQTPYFmmdanKEFUgd6RzzvBXDWfyqgBVvq\")))\n{\n\tstring hashedPassword = System.Convert.ToBase64String(hmac.ComputeHash(System.Text.Encoding.UTF8.GetBytes(plainPassword)));\n}"
  type: string
  minLength: 1
  maxLength: 255

When we validate our specification via swagger editor, the result looks like the following:

We expected the same result when displaying the very same yaml file in swagger ui, but the result was:

So it seems, like the markdown was not interpreted at all.
We use the Swashbucke.AspNetCore.SwaggerUI package in Version 5.0.0 on ASP.NET Core 2.2 to display the UI. Our specification is in swagger 2.0 format.

Is this related to this issue, or do you know if there is a workaround to have the markdown displayed correctly in SwaggerUI as well?

Thanks in regards,
Markus

[webron]

@mschmidt98 Swagger Editor uses Swagger UI for the rendering, so the result should be the same. Since you've mentioned you use a component from Swashbuckle, it's likely that whatever is provided there is a different version (which we don't control). Your best bet is to try integrating the latest version directly instead.

[mschmidt98]

The Swashbuckle release history hints, that the currently embedded version of swagger ui is 3.24.3.
I took from your release history that the last bugfix on your side regarding markdown was with 3.23.5, which should have been included, so the issue still remains...

[webron]

@mschmidt98 I've just tried with the latest version (3.25.0) and cannot reproduce the issue.