如何格式化Swagger 2.0文本描述？

Question

我想格式化我的Swagger API描述,以便它们不是简单的文本段落.最好,我想为它添加一个小桌子.

我没有在Swagger描述中找到有关文本格式的在线参考.如果我启动Swagger编辑器,并打开Instagram示例(File\Open Example\Instagram.yaml),我看到yaml文件中的第一个描述显示了一些格式,包括超链接和边界框:

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

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

这看起来像标准的Markdown,但是当我在样本描述中添加表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允许什么格式化？我做错了呈现一张桌子吗？

Answer 1

Swagger编辑器支持Markdown.下面是在OpenAPI(Swagger)文档中使用Markdown的示例:

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).

    An image:
    ![Swagger logo](https://raw.githubusercontent.com/swagger-api/swagger-ui/master/dist/favicon-32x32.png)

    Code block:

    ```
    {
      "message": "Hello, world!"
    }
    ```

    Tables:

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

您可以将上面的示例复制并粘贴到Swagger编辑器中以查看输出.