Как отформатировать текстовые описания Swagger 2.0?

Я хотел бы отформатировать описания Swagger API, чтобы они не были простыми абзацами текста. Предпочтительно, я хотел бы добавить к нему небольшую таблицу.

Я не нашел онлайн-ссылку на форматирование текста в описаниях Swagger. Если я запустил Редактор Swagger и откройте пример Instagram (File\Open Example\Instagram.yaml), я вижу первое описание в Файл yaml показывает некоторое форматирование, включая гиперссылку и ограничительную рамку:

    [registered your client](http://instagram.com/developer/register/) it easy
to start requesting data from Instagram.

```
  https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID
```

Это выглядит как стандартный Markdown, но когда я добавляю уценку таблицы к описанию образцов, редактор представляет ошибку:

|Col1|Col2|
|------|------|
|1|2|


YAML Syntax Error
End of the stream or a document separator is expected at line 36, column

Какое форматирование позволяет Swagger 2.0? Я делаю что-то неправильно, чтобы сделать таблицу?

Ответы

Ответ 1

Markdown поддерживается в swagger-editor, а ниже приведен пример использования Markdown в документе swagger:

swagger: '2.0'
info:
  version: 0.0.0
  title: Markdown 
  description: |
    # Heading

    Text attributes _italic_, *italic*, __bold__, **bold**, `monospace`.

    Horizontal rule:

    ---

    Bullet list:

      * apples
      * oranges
      * pears

    Numbered list:

      1. apples
      2. oranges
      3. pears

    A [link](http://example.com).

    Tables:

    | Column1 | Collumn2 |
    | ------- | -------- |
    | cell1   | cell2    |
paths:
  /:
    get:
      responses:
        200:
          description: OK

Вы можете скопировать и вставить приведенный выше пример в swagger-editor, чтобы увидеть результат.