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

Posted 2023-02-16

【中文标题】如何格式化 Swagger 2.0 文本描述？

【英文标题】：How to format Swagger 2.0 text descriptions?

【发布时间】：2017-02-16 20:39:02

【问题描述】：

我想格式化我的 Swagger API 描述，使它们不是简单的文本段落。最好是给它加一张小桌子。

我没有在 Swagger 描述中找到有关文本格式的在线参考。如果我启动Swagger Editor，并打开 Instagram 示例（文件\打开示例\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，但是当我在示例描述中添加表格降价时，编辑器会出现错误：

|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】：

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 | Column2 |
    | ------- | --------|
    | cell1   | cell2   |
paths:
  /:
    get:
      responses:
        200:
          description: OK

您可以将上面的示例复制并粘贴到Swagger Editor 以查看输出。

【讨论】：

啊。我知道为什么。 YAML 对缩进很敏感。我没有正确地做到这一点。谢谢威尔逊。

@Wilson，这种降价支持是否仅限于信息部分？当我将其复制/粘贴为 Pet 对象的描述时，它看起来与插入到信息部分时不同。谢谢！

@Stephen McFarland - 描述应该有“|”作为它的第一行，并且你想要在描述中的文本应该缩进。

@Stephen McFarland - 描述应该有“|”作为它的第一行，并且您想要在描述中的文本应该缩进。抱歉，我无法发表评论，因为我还没有 50 个代表。 由 fallenprogrammr 作为答案发布。以为我会很好，并在他们的“答案”被删除之前传递信息。

因此您无法真正关注 UI 中呈现的链接。不错。