swagger - 如何在 Swagger UI 3.x 中格式化描述中的代码块？

Question

我想在我的 API 描述中放置一个 Markdown 代码块，但 Swagger UI 似乎读起来好像它是一个单行代码片段。我目前有:

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"
        }
    }
    ```

这显示为:



但是，Swagger 编辑器会显示正确的代码块:



Swagger UI 不支持这个吗？

Answer 1

Swagger UI 3.22.0 和 Swagger Editor 3.6.26 中修复了代码块格式问题。代码块在这些版本中正确显示:



请注意文本中“a data 键”和“包含”之间的换行符 - 这是由 | literal block style 引起的。 ，它保留 YAML 多行字符串中的换行符。为避免该换行符，您可以 1) 在 YAML 中将其删除，或 2) 使用 > folded 样式并且还缩进代码块(以防止它被折叠)，如下所示:

  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"
          }
      }
      ```