How to format code blocks in descriptions in Swagger UI 3.x?

Question

I would like to put a Markdown code block in the description of my API but the Swagger UI seems to be reading as though it was a single line code snippet. I currently have:

description: |
    This API was created to allow interaction with the Image Status Database (ISD)

    ## Requests

    ## Responses
    In the case of a successful response, you will always receive a `data` key
    that contains your data.
    ```
    {
        "meta": {
            "code": 200
        },
        "data": {
            ...
        },
        "pagination": {
            "next_url": "...",
            "next_max_id": "13872296"
        }
    }
    ```

This gets displayed as:

The Swagger Editor, however, displays the proper code block:

Is this not supported by the Swagger UI?

Pena

Did you find a solution for this? – Neslund

@Neslund unfortunately I never did – Pena

Answer 1

The code block formatting issue was fixed in Swagger UI 3.22.0 and Swagger Editor 3.6.26. Code blocks are displayed properly in these versions:

Note the line break between "a data key" and "that contains" in the text - it is caused by the | literal block style, which preserves the line breaks in YAML multi-line strings. To avoid that line break you can either 1) remove it in your YAML, or 2) use the > folded style and also indent the code block (to prevent it from being folded), as shown below:

  description: >
    This API was created to allow interaction with the Image Status Database (ISD)

    ## Requests

    ## Responses

    In the case of a successful response, you will always receive a `data` key
    that contains your data.

      ```
      {
          "meta": {
              "code": 200
          },
          "data": {
              ...
          },
          "pagination": {
              "next_url": "...",
              "next_max_id": "13872296"
          }
      }
      ```

Idel