Как форматировать блоки кода в описаниях в Swagger UI 3.x?

Я хотел бы поместить блок кода Markdown в описание моего API, но пользовательский интерфейс Swagger, похоже, читается так, как будто это фрагмент кода из одной строки. В настоящее время у меня есть:

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 отображает правильный блок кода:

Снимок экрана редактора Swagger

Разве это не поддерживается пользовательским интерфейсом Swagger?


swagger swagger-ui swagger-2.0 swagger-editor
person Sara Tibbetts    schedule 19.04.2017    source источник
comment
Вы нашли решение для этого?   -  person Ian    schedule 15.03.2019
comment
@ Ян, к сожалению, я никогда этого не делал   -  person Sara Tibbetts    schedule 16.03.2019

Ответы (1)


arrow_upward
3
arrow_downward

Проблема форматирования блока кода была исправлена ​​в пользовательском интерфейсе Swagger 3.22.0 и редакторе Swagger 3.6.26. Блоки кода отображаются корректно в следующих версиях:

Блок кода Markdown, отображаемый пользовательским интерфейсом Swagger

Обратите внимание на разрыв строки между «ключом data» и «содержащим» в тексте — он вызван литеральным блоком | 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"
          }
      }
      ```
person Helen    schedule 26.03.2019